@pstdio/sdk 0.4.0 → 0.4.2

package/dist/client/client.d.ts

@@ -1,5 +1,6 @@
 import { type ActionClient } from "./actions";
 import { type AgentClient } from "./agents";
+import { type ExtensionClient } from "./extensions";
 import { type ProjectClient } from "./projects";
 import type { ClientOptions } from "./request";
 import { type SessionClient } from "./sessions";
@@ -20,5 +21,6 @@ export type PstdioClient = {
     skills: SkillClient;
     agents: AgentClient;
     actions: ActionClient;
+    extensions: ExtensionClient;
 };
 export declare const createClient: (options?: ClientOptions) => PstdioClient;

package/dist/client/extensions.d.ts

@@ -0,0 +1,7 @@
+import type { CommandExecuteRequest, CommandExecuteResponse, EnableInstalledExtensionRequest, EnableInstalledExtensionResponse } from "pstdio-api-contracts";
+import type { RequestFn } from "./request";
+export type ExtensionClient = {
+    enableInstalled(projectId: string, installName: string, request: EnableInstalledExtensionRequest): Promise<EnableInstalledExtensionResponse>;
+    execute(commandId: string, request: CommandExecuteRequest): Promise<CommandExecuteResponse>;
+};
+export declare const createExtensionClient: (request: RequestFn) => ExtensionClient;

package/dist/client/index.d.ts

@@ -1,6 +1,7 @@
 export type { ActionClient } from "./actions";
 export type { AgentClient } from "./agents";
 export { createClient, type PstdioClient } from "./client";
+export type { ExtensionClient } from "./extensions";
 export type { ProjectClient } from "./projects";
 export { type ClientOptions, createRequest, PstdioApiError, type RequestFn } from "./request";
 export type { SessionClient } from "./sessions";

package/dist/client/index.js

@@ -18,6 +18,21 @@ var createAgentClient = (request) => ({
   delete: (agentId) => request(`/v1/agents/${agentId}`, { method: "DELETE" })
 });
 
+// src/client/extensions.ts
+var createExtensionClient = (request) => ({
+  enableInstalled: (projectId, installName, body) => request(`/v1/projects/${projectId}/extensions/installed/${encodeURIComponent(installName)}/enable`, {
+    method: "POST",
+    body
+  }),
+  execute: (commandId, input) => {
+    const { projectId, ...body } = input;
+    return request(`/v1/projects/${projectId}/extensions/commands/${encodeURIComponent(commandId)}/execute`, {
+      method: "POST",
+      body
+    });
+  }
+});
+
 // src/client/projects.ts
 var createProjectClient = (request) => ({
   list: () => request("/v1/projects"),
@@ -298,7 +313,8 @@ var createClient = (options = {}) => {
     templates: createTemplateClient(request),
     skills: createSkillClient(request),
     agents: createAgentClient(request),
-    actions: createActionClient(request)
+    actions: createActionClient(request),
+    extensions: createExtensionClient(request)
   };
 };
 export {

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

@@ -0,0 +1,28 @@
+import type { CommandDefinition, HookDefinition, MiddlewareDefinition } from "./types/extension";
+import type { Struct } from "./types/json";
+import type { ParamObjectSchema } from "./types/params";
+/**
+ * Define a single command outside an extension's object literal. Use this when commands
+ * grow large enough to split into separate files, or when you need to share a command
+ * shape across extensions. The `params` schema drives the inferred shape of `ctx.params`.
+ *
+ * @example
+ *   export const sayHello = defineCommand({
+ *     title: "Say hello",
+ *     params: { name: params.text() },
+ *     async run(ctx) {
+ *       ctx.params.name; // string
+ *     },
+ *   });
+ */
+export declare const defineCommand: <const TSchema extends ParamObjectSchema | undefined, TResult = unknown>(definition: CommandDefinition<TSchema, TResult>) => CommandDefinition<TSchema, TResult>;
+/**
+ * Define middleware for a command. Pass the typed `command` ref (preferred) or
+ * `commandId` for cross-extension references where the typed ref isn't importable.
+ */
+export declare const defineMiddleware: <TParams extends Struct = Struct, TResult = unknown>(definition: MiddlewareDefinition<TParams, TResult>) => MiddlewareDefinition<TParams, TResult>;
+/**
+ * Define a hook for an event. Pass the typed `event` ref (preferred) or `eventId` for
+ * cross-extension references where the typed ref isn't importable.
+ */
+export declare const defineHook: <TPayload extends Struct = Struct>(definition: HookDefinition<TPayload>) => HookDefinition<TPayload>;

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

@@ -0,0 +1,16 @@
+import type { ExtensionDefinition } from "./types/extension";
+/**
+ * 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.
+ *
+ * @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;

package/dist/extensions/index.d.ts

@@ -0,0 +1,8 @@
+export { defineCommand, defineHook, defineMiddleware } from "./define-command";
+export { defineExtension } from "./define-extension";
+export { projectEvents, projectSlots, sessionEvents, sessionSlots, workspaceEvents, workspaceSlots, } from "./kernel-slots";
+export { packageAsset } from "./package-asset";
+export { params } from "./params";
+export { commandEvent, commandRef, commandsOf, eventRef } from "./refs";
+export { defineSlot } from "./slots";
+export type * from "./types";

package/dist/extensions/index.js

@@ -0,0 +1,111 @@
+// src/extensions/define-command.ts
+var defineCommand = (definition) => definition;
+var defineMiddleware = (definition) => definition;
+var defineHook = (definition) => definition;
+// src/extensions/define-extension.ts
+var defineExtension = (extension) => extension;
+// src/extensions/refs.ts
+var commandRef = (id) => ({ id });
+var eventRef = (id) => ({ id });
+var commandEvent = (command, phase) => ({
+  id: `command.${phase}:${command.id}`
+});
+var commandsOf = (extension) => {
+  const refs = {};
+  const commands = extension.commands ?? {};
+  for (const key of Object.keys(commands)) {
+    refs[key] = { id: `${extension.namespace}.${key}` };
+  }
+  return refs;
+};
+
+// src/extensions/slots.ts
+var defineSlot = (id, options) => ({
+  id,
+  kind: options.kind,
+  label: options.label,
+  description: options.description,
+  metadata: options.metadata
+});
+
+// src/extensions/kernel-slots.ts
+var projectSlots = {
+  sidebarNav: defineSlot("project.sidebarNav", { kind: "navigation" }),
+  sidebar: defineSlot("project.sidebar", { kind: "view" }),
+  headerPrimary: defineSlot("project.headerPrimary", { kind: "menu" }),
+  headerOverflow: defineSlot("project.headerOverflow", { kind: "menu" }),
+  settingsPanels: defineSlot("project.settingsPanels", { kind: "settings" })
+};
+var sessionSlots = {
+  headerPrimary: defineSlot("session.headerPrimary", { kind: "menu" }),
+  headerOverflow: defineSlot("session.headerOverflow", { kind: "menu" }),
+  transcriptActions: defineSlot("session.transcriptActions", { kind: "menu" })
+};
+var workspaceSlots = {
+  headerPrimary: defineSlot("workspace.headerPrimary", { kind: "menu" }),
+  headerOverflow: defineSlot("workspace.headerOverflow", { kind: "menu" }),
+  tabs: defineSlot("workspace.tabs", { kind: "navigation" }),
+  sidebar: defineSlot("workspace.sidebar", { kind: "view" })
+};
+var projectEvents = {
+  opened: eventRef("project.opened")
+};
+var sessionEvents = {
+  started: eventRef("session.started"),
+  completed: eventRef("session.completed")
+};
+var workspaceEvents = {
+  created: eventRef("workspace.created"),
+  archived: eventRef("workspace.archived"),
+  deleted: eventRef("workspace.deleted")
+};
+// src/extensions/package-asset.ts
+var packageAsset = (path, baseUrl) => ({
+  kind: "package-asset",
+  path,
+  baseUrl
+});
+// src/extensions/params.ts
+var params = {
+  text: (options = {}) => ({ type: "text", ...options }),
+  longText: (options = {}) => ({ type: "longtext", ...options }),
+  number: (options = {}) => ({ type: "number", ...options }),
+  boolean: (options = {}) => ({ type: "boolean", ...options }),
+  select: (options) => ({ type: "select", ...options }),
+  multiSelect: (options) => ({
+    type: "multi-select",
+    ...options
+  }),
+  repo: (options = {}) => ({ type: "repo", ...options }),
+  harness: (options = {}) => ({ type: "harness", ...options }),
+  template: (options) => ({
+    label: options.label,
+    description: options.description,
+    required: options.required,
+    defaultValue: options.defaultValue,
+    metadata: options.metadata,
+    type: "template",
+    templateType: options.type
+  }),
+  resource: (options) => ({ type: "resource", ...options }),
+  json: (options = {}) => ({ type: "json", ...options })
+};
+export {
+  workspaceSlots,
+  workspaceEvents,
+  sessionSlots,
+  sessionEvents,
+  projectSlots,
+  projectEvents,
+  params,
+  packageAsset,
+  eventRef,
+  defineSlot,
+  defineMiddleware,
+  defineHook,
+  defineExtension,
+  defineCommand,
+  commandsOf,
+  commandRef,
+  commandEvent
+};

package/dist/extensions/kernel-slots.d.ts

@@ -0,0 +1,46 @@
+import type { JsonObject } from "./types/json";
+import type { ResourceAnchor } from "./types/resources";
+export declare const projectSlots: {
+    sidebarNav: import("./types").SlotRef<object, "navigation">;
+    sidebar: import("./types").SlotRef<object, "view">;
+    headerPrimary: import("./types").SlotRef<object, "menu">;
+    headerOverflow: import("./types").SlotRef<object, "menu">;
+    settingsPanels: import("./types").SlotRef<object, "settings">;
+};
+export declare const sessionSlots: {
+    headerPrimary: import("./types").SlotRef<object, "menu">;
+    headerOverflow: import("./types").SlotRef<object, "menu">;
+    transcriptActions: import("./types").SlotRef<object, "menu">;
+};
+export declare const workspaceSlots: {
+    headerPrimary: import("./types").SlotRef<object, "menu">;
+    headerOverflow: import("./types").SlotRef<object, "menu">;
+    tabs: import("./types").SlotRef<object, "navigation">;
+    sidebar: import("./types").SlotRef<object, "view">;
+};
+export declare const projectEvents: {
+    opened: import("./types").EventRef<{
+        projectId: string;
+    }>;
+};
+export declare const sessionEvents: {
+    started: import("./types").EventRef<{
+        sessionId: string;
+        anchors?: ResourceAnchor[];
+    }>;
+    completed: import("./types").EventRef<{
+        sessionId: string;
+        anchors?: ResourceAnchor[];
+    }>;
+};
+export declare const workspaceEvents: {
+    created: import("./types").EventRef<{
+        workspace: JsonObject;
+    }>;
+    archived: import("./types").EventRef<{
+        workspace: JsonObject;
+    }>;
+    deleted: import("./types").EventRef<{
+        workspace: JsonObject;
+    }>;
+};

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

@@ -0,0 +1,10 @@
+import type { PackageAssetDescriptor } from "./types/resources";
+/**
+ * Reference an asset shipped alongside the extension's compiled output. `path` is
+ * resolved relative to `baseUrl`; in practice authors always pass `import.meta.url`
+ * so the runtime can locate the file no matter where the extension is installed.
+ *
+ * @example
+ *   webview: { entry: packageAsset("./dist/page.html", import.meta.url) }
+ */
+export declare const packageAsset: (path: string, baseUrl: string) => PackageAssetDescriptor;

package/dist/extensions/params.d.ts

@@ -0,0 +1,26 @@
+import type { BooleanParam, HarnessParam, JsonParam, LongTextParam, MultiSelectParam, NumberParam, RepoParam, ResourceParam, SelectParam, TemplateParam, TextParam } from "./types/params";
+/**
+ * Builders for typed parameter descriptors. Each builder produces a discriminated
+ * `ParamDescriptor` so the runtime and editor only see fields valid for that type.
+ *
+ * @example
+ *   params: {
+ *     amount: params.number({ defaultValue: 1 }),
+ *     mode: params.select({ options: [{ label: "Fast", value: "fast" }] }),
+ *   }
+ */
+export declare const params: {
+    text: (options?: Omit<TextParam, "type">) => TextParam;
+    longText: (options?: Omit<LongTextParam, "type">) => LongTextParam;
+    number: (options?: Omit<NumberParam, "type">) => NumberParam;
+    boolean: (options?: Omit<BooleanParam, "type">) => BooleanParam;
+    select: (options: Omit<SelectParam, "type">) => SelectParam;
+    multiSelect: (options: Omit<MultiSelectParam, "type">) => MultiSelectParam;
+    repo: (options?: Omit<RepoParam, "type">) => RepoParam;
+    harness: (options?: Omit<HarnessParam, "type">) => HarnessParam;
+    template: (options: Omit<TemplateParam, "type" | "templateType"> & {
+        type: string;
+    }) => TemplateParam;
+    resource: (options: Omit<ResourceParam, "type">) => ResourceParam;
+    json: <T = unknown>(options?: Omit<JsonParam<T>, "type">) => JsonParam<T>;
+};

package/dist/extensions/refs.d.ts

@@ -0,0 +1,38 @@
+import type { CommandLifecycleEventPayload, CommandLifecyclePhase, CommandRef } from "./types/commands";
+import type { EventRef } from "./types/events";
+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.
+ */
+export declare const commandRef: <TParams extends Struct = Struct, TResult = unknown>(id: string) => CommandRef<TParams, TResult>;
+/** Build a typed reference to an event by id. */
+export declare const eventRef: <TPayload extends Struct = Struct>(id: string) => EventRef<TPayload>;
+/**
+ * Build an `EventRef` for a command lifecycle phase (`requested`, `started`, `completed`,
+ * `rejected`, `failed`). The payload type is inferred from the command ref so hooks see
+ * the correct shape.
+ */
+export declare const commandEvent: <TPhase extends CommandLifecyclePhase, TParams extends Struct = Struct, TResult = unknown>(command: CommandRef<TParams, TResult>, phase: TPhase) => EventRef<CommandLifecycleEventPayload<TPhase, TParams, TResult>>;
+type CommandsRecord = Record<string, CommandDefinition<any, any>>;
+type CommandRefFromDefinition<TDefinition> = TDefinition extends CommandDefinition<infer TSchema, infer TResult> ? CommandRef<TSchema extends ParamObjectSchema ? ParamsOf<TSchema> : Struct, TResult> : never;
+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.
+ *
+ * @example
+ *   const ext = defineExtension({ id: "lab", namespace: "lab", commands: { ... } });
+ *   const labCommands = commandsOf(ext);
+ *   labCommands.awaken; // CommandRef<{ title: string }, ...>
+ */
+export declare const commandsOf: <TExtension extends {
+    namespace: string;
+    commands?: CommandsRecord;
+}>(extension: TExtension) => CommandsRefMap<NonNullable<TExtension["commands"]>>;
+export {};

package/dist/extensions/slots.d.ts

@@ -0,0 +1,14 @@
+import type { Struct } from "./types/json";
+import type { SlotOptions, SlotRef, UiSlotKind } from "./types/slots";
+/**
+ * Define a UI slot that contributions can target. The `TContext` parameter constrains
+ * the data passed to renderers/menus invoked through the slot, and `TKind` picks the
+ * contribution shape (`menu`, `navigation`, `view`, `settings`, `renderer`).
+ *
+ * @example
+ *   export const projectHeader = defineSlot<{ projectId: string }, "menu">("project.header", {
+ *     kind: "menu",
+ *     label: "Project header",
+ *   });
+ */
+export declare const defineSlot: <TContext extends Struct = Struct, TKind extends UiSlotKind = UiSlotKind>(id: string, options: SlotOptions<TKind>) => SlotRef<TContext, TKind>;

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

@@ -0,0 +1,117 @@
+import type { JsonObject, JsonValue, Struct } from "./json";
+import type { RepoContext, ResourceRef } from "./resources";
+import type { SlotInvocationContext } from "./slots";
+export type CommandSource = "cli" | "dashboard" | "api" | "schedule" | "event" | "automation" | "command-panel";
+export interface CommandRef<TParams extends Struct = Struct, TResult = unknown> {
+    id: string;
+    params?: TParams;
+    result?: TResult;
+}
+export interface SerializedError {
+    name?: string;
+    message: string;
+    stack?: string;
+    cause?: JsonValue;
+}
+export interface CommandInvocation<TParams extends Struct = Struct> {
+    params: TParams;
+    resource?: ResourceRef;
+    repoId?: string;
+    repoPath?: string;
+    slot?: SlotInvocationContext;
+    metadata?: JsonObject;
+}
+export interface CommandContinue {
+    type: "continue";
+}
+export interface CommandPatchParams<TParams extends Struct = Struct> {
+    type: "patchParams";
+    params: Partial<TParams>;
+}
+export interface CommandReplaceParams<TParams extends Struct = Struct> {
+    type: "replaceParams";
+    params: TParams;
+}
+export interface CommandReplaceInvocation<TParams extends Struct = Struct> {
+    type: "replaceInvocation";
+    invocation: CommandInvocation<TParams>;
+}
+export interface CommandReject {
+    type: "reject";
+    code?: string;
+    reason: string;
+    data?: JsonObject;
+}
+export type CommandMiddlewareResult<TParams extends Struct = Struct> = void | CommandContinue | CommandPatchParams<TParams> | CommandReplaceParams<TParams> | CommandReplaceInvocation<TParams> | CommandReject;
+export interface CommandNotice {
+    type: "info" | "success" | "warning" | "error";
+    title?: string;
+    message: string;
+    metadata?: JsonObject;
+}
+export interface CommandDiagnostic {
+    code: string;
+    message: string;
+    severity: "info" | "warning" | "error";
+    extensionId?: string;
+    commandId?: string;
+    metadata?: JsonObject;
+}
+export type CommandOutcome<TResult = unknown> = {
+    ok: true;
+    status: "success";
+    value: TResult;
+    notices?: CommandNotice[];
+    diagnostics?: CommandDiagnostic[];
+} | {
+    ok: false;
+    status: "rejected";
+    code?: string;
+    reason: string;
+    data?: JsonObject;
+    notices?: CommandNotice[];
+    diagnostics?: CommandDiagnostic[];
+} | {
+    ok: false;
+    status: "error";
+    code?: string;
+    reason: string;
+    error?: SerializedError;
+    notices?: CommandNotice[];
+    diagnostics?: CommandDiagnostic[];
+};
+export interface CommandHelpersApi {
+    execute<TParams extends Struct = Struct, TResult = unknown>(command: CommandRef<TParams, TResult> | string, invocation: CommandInvocation<TParams>): Promise<CommandOutcome<TResult>>;
+    continue(): CommandContinue;
+    patchParams<TParams extends Struct = Struct>(params: Partial<TParams>): CommandPatchParams<TParams>;
+    replaceParams<TParams extends Struct = Struct>(params: TParams): CommandReplaceParams<TParams>;
+    replaceInvocation<TParams extends Struct = Struct>(invocation: CommandInvocation<TParams>): CommandReplaceInvocation<TParams>;
+    reject(input: Omit<CommandReject, "type">): CommandReject;
+}
+export interface CommandRequestedEvent<TParams extends Struct = Struct> {
+    commandId: string;
+    invocationId: string;
+    source?: CommandSource;
+    params: TParams;
+    resource?: ResourceRef;
+    repo?: RepoContext;
+}
+export interface CommandStartedEvent<TParams extends Struct = Struct> extends CommandRequestedEvent<TParams> {
+}
+export interface CommandCompletedEvent<TParams extends Struct = Struct, TResult = unknown> extends CommandStartedEvent<TParams> {
+    result: TResult;
+    elapsedMs: number;
+}
+export interface CommandRejectedEvent<TParams extends Struct = Struct> extends CommandRequestedEvent<TParams> {
+    code?: string;
+    reason: string;
+    data?: JsonObject;
+}
+export interface CommandFailedEvent<TParams extends Struct = Struct> extends CommandRequestedEvent<TParams> {
+    code?: string;
+    reason: string;
+    error?: SerializedError;
+    elapsedMs: number;
+}
+export type CommandLifecyclePhase = "requested" | "started" | "completed" | "rejected" | "failed";
+export type CommandLifecycleEventPayload<TPhase extends CommandLifecyclePhase, TParams extends Struct = Struct, TResult = unknown> = TPhase extends "requested" ? CommandRequestedEvent<TParams> : TPhase extends "started" ? CommandStartedEvent<TParams> : TPhase extends "completed" ? CommandCompletedEvent<TParams, TResult> : TPhase extends "rejected" ? CommandRejectedEvent<TParams> : CommandFailedEvent<TParams>;

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

@@ -0,0 +1,188 @@
+import type { CommandHelpersApi, CommandInvocation, CommandMiddlewareResult, CommandNotice, CommandSource } from "./commands";
+import type { EventDeliveryResult, EventRef } from "./events";
+import type { JsonObject, MaybePromise, Struct } from "./json";
+import type { RepoContext, ResourceAnchor, ResourceRef } from "./resources";
+import type { SlotInvocationContext } from "./slots";
+export interface ExtensionStorageCollectionApi<TItem = unknown> {
+    get(id: string): Promise<TItem | undefined>;
+    list(): Promise<TItem[]>;
+    put(id: string, value: TItem): Promise<void>;
+    create(value: TItem): Promise<TItem & {
+        id: string;
+    }>;
+    delete(id: string): Promise<void>;
+}
+export type StorageScope = {
+    type: "project";
+} | {
+    type: "repo";
+    repoId?: string;
+} | {
+    type: "resource";
+    resource?: ResourceRef;
+} | {
+    type: string;
+    id?: string;
+};
+export interface ExtensionStorageApi {
+    scope(scope: StorageScope): ExtensionStorageApi;
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set<T = unknown>(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<void>;
+    collection<TItem = unknown>(name: string): ExtensionStorageCollectionApi<TItem>;
+}
+export interface ArtifactFile {
+    path: string;
+    size?: number;
+    updatedAt?: string;
+}
+export interface ArtifactMount {
+    exists(path: string): Promise<boolean>;
+    readText(path: string): Promise<string>;
+    writeText(path: string, value: string): Promise<void>;
+    readBytes(path: string): Promise<Uint8Array>;
+    writeBytes(path: string, value: Uint8Array): Promise<void>;
+    list(pattern?: string): Promise<ArtifactFile[]>;
+    listDirs(path?: string): Promise<string[]>;
+    delete(path: string): Promise<void>;
+}
+export interface ExtensionArtifactApi {
+    mount(key: string): ArtifactMount;
+}
+export interface ExtensionFilesApi {
+    readText(fileId: string): Promise<string>;
+    writeText(fileId: string, value: string): Promise<void>;
+    createText(input: {
+        name: string;
+        content: string;
+        metadata?: JsonObject;
+    }): Promise<{
+        id: string;
+    }>;
+    delete(fileId: string): Promise<void>;
+}
+export interface ExtensionSessionsApi {
+    create(input: {
+        title: string;
+        prompt?: string;
+        template?: string;
+        vars?: JsonObject;
+        harness?: unknown;
+        workspaceId?: string;
+        repoId?: string;
+        anchors?: ResourceAnchor[];
+        originalSessionId?: string;
+    }): Promise<{
+        id: string;
+    }>;
+    followup(input: {
+        sessionId: string;
+        prompt?: string;
+        template?: string;
+        vars?: JsonObject;
+    }): Promise<void>;
+}
+export interface ExtensionWorkspacesApi {
+    get(id: string): Promise<unknown>;
+    create(input: JsonObject): Promise<unknown>;
+    archive(id: string): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+export interface ExtensionReposApi {
+    list(): Promise<RepoContext[]>;
+    get(repoId: string): Promise<RepoContext>;
+    getDefault(): Promise<RepoContext | undefined>;
+    resolvePath(repoId: string, relativePath: string, options?: {
+        basePath?: string;
+    }): Promise<string>;
+}
+export interface ExtensionEventsApi {
+    emit<TPayload extends Struct>(event: EventRef<TPayload> | string, payload: TPayload): Promise<EventDeliveryResult>;
+}
+export interface ExtensionActivityApi {
+    record(input: {
+        message: string;
+        target?: ResourceRef;
+        related?: ResourceRef[];
+        metadata?: JsonObject;
+    }): Promise<{
+        id: string;
+    }>;
+}
+export interface ExtensionNotifyApi {
+    toast(notice: CommandNotice): Promise<void>;
+}
+export interface ProcessRunResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+export interface ExtensionProcessApi {
+    run(input: {
+        command: string[];
+        cwd?: string;
+        env?: Record<string, string>;
+        timeoutMs?: number;
+    }): Promise<ProcessRunResult>;
+    spawnDetached(input: {
+        command: string[];
+        cwd?: string;
+        env?: Record<string, string>;
+    }): Promise<{
+        pid?: number;
+    }>;
+}
+export interface ExtensionNetApi {
+    findFreePort(input?: {
+        host?: string;
+    }): Promise<number>;
+}
+export interface ExtensionLoggerApi {
+    info(message: string, metadata?: JsonObject): void;
+    warn(message: string, metadata?: JsonObject): void;
+    error(message: string, metadata?: JsonObject): void;
+}
+export interface ExtensionSettingsApi<TSettings extends Struct = Struct> {
+    all(): Promise<Partial<TSettings>>;
+    get<TKey extends keyof TSettings>(key: TKey): Promise<TSettings[TKey] | undefined>;
+    set<TKey extends keyof TSettings>(key: TKey, value: TSettings[TKey]): Promise<void>;
+    delete<TKey extends keyof TSettings>(key: TKey): Promise<void>;
+}
+export interface ExtensionContextBase {
+    projectId: string;
+    extensionId: string;
+    namespace: string;
+    repo?: RepoContext;
+    source?: CommandSource;
+    storage: ExtensionStorageApi;
+    artifacts: ExtensionArtifactApi;
+    files: ExtensionFilesApi;
+    sessions: ExtensionSessionsApi;
+    workspaces: ExtensionWorkspacesApi;
+    repos: ExtensionReposApi;
+    commands: CommandHelpersApi;
+    events: ExtensionEventsApi;
+    activity: ExtensionActivityApi;
+    notify: ExtensionNotifyApi;
+    process: ExtensionProcessApi;
+    net: ExtensionNetApi;
+    logger: ExtensionLoggerApi;
+    settings: ExtensionSettingsApi;
+}
+export interface CommandContext<TParams extends Struct = Struct> extends ExtensionContextBase {
+    commandId: string;
+    invocationId: string;
+    invocation: CommandInvocation<TParams>;
+    resource?: ResourceRef;
+    slot?: SlotInvocationContext;
+    params: TParams;
+}
+export type CommandMiddlewareContext<TParams extends Struct = Struct> = CommandContext<TParams>;
+export type CommandMiddlewareHandler<TParams extends Struct = Struct> = (ctx: CommandMiddlewareContext<TParams>) => MaybePromise<CommandMiddlewareResult<TParams>>;
+export type CommandRunHandler<TParams extends Struct = Struct, TResult = unknown> = (ctx: CommandContext<TParams>) => MaybePromise<TResult>;
+export interface EventContext extends ExtensionContextBase {
+    eventId: string;
+    deliveryId: string;
+}
+export type SetupContext = ExtensionContextBase;
+export type MigrationContext = ExtensionContextBase;

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

@@ -0,0 +1,92 @@
+import type { CommandRef, CommandSource } from "./commands";
+import type { JsonObject, Struct } from "./json";
+import type { PackageAssetDescriptor } from "./resources";
+import type { SlotRef } from "./slots";
+export interface CliContribution {
+    path?: string[];
+    globalAliases?: string[][];
+    description?: string;
+    examples?: string[];
+    hidden?: boolean;
+}
+export interface WhenExpression {
+    source?: CommandSource[];
+    resourceType?: string[];
+    metadata?: JsonObject;
+}
+export interface CommandPanelContribution {
+    group?: string;
+    keywords?: string[];
+    when?: WhenExpression;
+}
+export interface MenuContribution<TSlotContext extends Struct = Struct, TParams extends Struct = Struct> {
+    slot: SlotRef<TSlotContext, "menu"> | string;
+    label?: string;
+    group?: string;
+    placement?: "first" | "default" | "last";
+    icon?: string;
+    when?: WhenExpression;
+    command?: CommandRef<TParams, unknown> | string;
+    params?: Partial<TParams>;
+    presentation?: "menu-item" | "button" | "icon-button";
+}
+export interface NavigationContribution<TSlotContext extends Struct = Struct, TParams extends Struct = Struct> {
+    slot: SlotRef<TSlotContext, "navigation"> | string;
+    label: string;
+    group?: string;
+    placement?: "first" | "default" | "last";
+    route?: string;
+    href?: string;
+    command?: CommandRef<TParams, unknown> | string;
+    params?: Partial<TParams>;
+    icon?: string;
+    when?: WhenExpression;
+}
+export interface WebviewContribution {
+    entry: PackageAssetDescriptor;
+    title?: string;
+    sandbox?: "default" | "strict";
+}
+export interface ViewContribution<TSlotContext extends Struct = Struct> {
+    title: string;
+    slot: SlotRef<TSlotContext, "view"> | string;
+    group?: string;
+    placement?: "first" | "default" | "last";
+    webview: WebviewContribution;
+}
+export interface RouteContribution {
+    path: string;
+    label: string;
+    webview: WebviewContribution;
+}
+export interface SettingsPanelContribution<TSlotContext extends Struct = Struct> {
+    title: string;
+    slot: SlotRef<TSlotContext, "settings"> | string;
+    webview: WebviewContribution;
+}
+export interface RendererContribution<TSlotContext extends Struct = Struct> {
+    slot: SlotRef<TSlotContext, "renderer"> | string;
+    for: string;
+    webview: WebviewContribution;
+}
+export interface ArtifactMountContribution {
+    /** Relative path under .pstdio/<extension.namespace>/. */
+    path: string;
+    label: string;
+    repoRole?: "default" | "selected" | "workspace";
+}
+export interface TemplateTypeContribution {
+    label: string;
+    description?: string;
+}
+export interface TemplateContribution {
+    title: string;
+    type: string;
+    source: PackageAssetDescriptor;
+    description?: string;
+}
+export interface SkillContribution {
+    title: string;
+    source: PackageAssetDescriptor;
+    description?: string;
+}

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

@@ -0,0 +1,10 @@
+import type { CommandDiagnostic } from "./commands";
+import type { Struct } from "./json";
+export interface EventRef<TPayload extends Struct = Struct> {
+    id: string;
+    payload?: TPayload;
+}
+export interface EventDeliveryResult {
+    delivered: number;
+    diagnostics?: CommandDiagnostic[];
+}

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

@@ -0,0 +1,158 @@
+import type { CommandRef } from "./commands";
+import type { CommandMiddlewareHandler, CommandRunHandler, EventContext, ExtensionContextBase, MigrationContext, SetupContext } from "./context";
+import type { ArtifactMountContribution, CliContribution, CommandPanelContribution, MenuContribution, NavigationContribution, RendererContribution, RouteContribution, SettingsPanelContribution, SkillContribution, TemplateContribution, TemplateTypeContribution, 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";
+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
+ * the inferred shape of `ctx.params` in `run`.
+ */
+export interface CommandDefinition<TSchema extends ParamObjectSchema | undefined = ParamObjectSchema | undefined, TResult = unknown> {
+    title: string;
+    description?: string;
+    params?: TSchema;
+    /** Defaults to true. */
+    commandPanel?: boolean | CommandPanelContribution;
+    menus?: MenuContribution[];
+    cli?: boolean | CliContribution;
+    run: CommandRunHandler<SchemaParams<TSchema>, TResult>;
+}
+/**
+ * Middleware that runs before a command. Use `command` for a typed `CommandRef`; use
+ * `commandId` only when referencing a command from another extension you don't import.
+ */
+export interface MiddlewareDefinition<TParams extends Struct = Struct, TResult = unknown> {
+    command?: CommandRef<TParams, TResult>;
+    commandId?: string;
+    handler: CommandMiddlewareHandler<TParams>;
+}
+/**
+ * A handler for an event. Use `event` for a typed `EventRef`; use `eventId` for events
+ * you cannot import (e.g. originating in another extension).
+ */
+export interface HookDefinition<TPayload extends Struct = Struct> {
+    event?: EventRef<TPayload>;
+    eventId?: string;
+    handler(ctx: EventContext, payload: TPayload): MaybePromise<void>;
+}
+export interface ScheduleContribution<TParams extends Struct = Struct> {
+    title: string;
+    cron: string;
+    command?: CommandRef<TParams, unknown>;
+    commandId?: string;
+    params?: TParams;
+    repoId?: string;
+    repoPath?: string;
+    disabled?: boolean;
+}
+export interface HarnessDetectionResult {
+    available: boolean;
+    version?: string;
+    reason?: string;
+}
+export interface HarnessRun {
+    runId: string;
+    pid?: number;
+    metadata?: JsonObject;
+}
+export interface HarnessProvider {
+    id: string;
+    label: string;
+    detect?(ctx: ExtensionContextBase): MaybePromise<HarnessDetectionResult>;
+    start(ctx: ExtensionContextBase, input: {
+        workspacePath: string;
+        sessionId: string;
+        prompt?: string;
+    }): MaybePromise<HarnessRun>;
+    send?(ctx: ExtensionContextBase, input: {
+        runId: string;
+        message: string;
+    }): MaybePromise<void>;
+    stop?(ctx: ExtensionContextBase, input: {
+        runId: string;
+    }): MaybePromise<void>;
+}
+export interface WorkspaceTypeProvider {
+    id: string;
+    label: string;
+    create(ctx: ExtensionContextBase, input: JsonObject): MaybePromise<JsonObject>;
+    resolve(ctx: ExtensionContextBase, workspace: JsonObject): MaybePromise<{
+        rootPath: string;
+        displayPath?: string;
+    }>;
+    archive?(ctx: ExtensionContextBase, workspace: JsonObject): MaybePromise<void>;
+    delete?(ctx: ExtensionContextBase, workspace: JsonObject): MaybePromise<void>;
+}
+export interface LocalExtensionSource {
+    name: string;
+    path: string;
+    origin?: string;
+    installedAt: string;
+    updatedAt: string;
+}
+export interface ProjectExtensionInstance {
+    projectId: string;
+    extensionId: string;
+    namespace: string;
+    sourceName: string;
+    enabled: boolean;
+    config: JsonObject;
+}
+/** Identifying metadata for an extension. */
+export interface ExtensionMetadata {
+    id: string;
+    namespace: string;
+    name: string;
+    version?: string;
+    description?: string;
+    /** Manifest API version. The runtime uses this to detect incompatible extensions. */
+    apiVersion: ExtensionApiVersion;
+    settings?: ParamObjectSchema;
+}
+/** UI surface contributions: slots, routes, panels, renderers. */
+export interface UiContributions {
+    slots?: Record<string, SlotRef>;
+    routes?: Record<string, RouteContribution>;
+    views?: Record<string, ViewContribution>;
+    navigation?: Record<string, NavigationContribution>;
+    settingsPanels?: Record<string, SettingsPanelContribution>;
+    activityRenderers?: Record<string, RendererContribution>;
+    sessionAnchorRenderers?: Record<string, RendererContribution>;
+}
+/** Behavioural surface: commands, middleware, hooks, schedules. */
+export interface BehaviourContributions {
+    commands?: Record<string, CommandDefinition<any, any>>;
+    middlewares?: Record<string, MiddlewareDefinition<any, any>>;
+    hooks?: Record<string, HookDefinition<any>>;
+    schedules?: Record<string, ScheduleContribution<any>>;
+}
+/** Static asset contributions: artifact mounts, templates, skills. */
+export interface AssetContributions {
+    artifactMounts?: Record<string, ArtifactMountContribution>;
+    templateTypes?: Record<string, TemplateTypeContribution>;
+    templates?: Record<string, TemplateContribution>;
+    skills?: Record<string, SkillContribution>;
+}
+/** Provider contributions: harnesses, workspace types. */
+export interface ProviderContributions {
+    workspaceTypes?: Record<string, WorkspaceTypeProvider>;
+    harnesses?: Record<string, HarnessProvider>;
+}
+/** Lifecycle hooks invoked by the runtime when an extension is installed or upgraded. */
+export interface ExtensionLifecycle {
+    initialSetup?: (ctx: SetupContext) => MaybePromise<void>;
+    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.
+ */
+export interface ExtensionDefinition extends ExtensionMetadata, UiContributions, BehaviourContributions, AssetContributions, ProviderContributions, ExtensionLifecycle {
+}
+export type ExtensionSourceKind = "local" | "package" | "builtin";
+export {};

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

@@ -0,0 +1,9 @@
+export type * from "./commands";
+export type * from "./context";
+export type * from "./contributions";
+export type * from "./events";
+export type * from "./extension";
+export type * from "./json";
+export type * from "./params";
+export type * from "./resources";
+export type * from "./slots";

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

@@ -0,0 +1,7 @@
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | JsonObject;
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+export type MaybePromise<T> = T | Promise<T>;
+export type Struct = object;

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

@@ -0,0 +1,66 @@
+import type { JsonObject } from "./json";
+import type { ResourceRef } from "./resources";
+export type ParamType = "text" | "longtext" | "number" | "boolean" | "select" | "multi-select" | "repo" | "harness" | "template" | "resource" | "json";
+interface ParamBase<TValue> {
+    label?: string;
+    description?: string;
+    required?: boolean;
+    defaultValue?: TValue;
+    metadata?: JsonObject;
+}
+export interface TextParam extends ParamBase<string> {
+    type: "text";
+}
+export interface LongTextParam extends ParamBase<string> {
+    type: "longtext";
+}
+export interface NumberParam extends ParamBase<number> {
+    type: "number";
+}
+export interface BooleanParam extends ParamBase<boolean> {
+    type: "boolean";
+}
+export interface SelectParam extends ParamBase<string> {
+    type: "select";
+    options: Array<{
+        label: string;
+        value: string;
+    }>;
+}
+export interface MultiSelectParam extends ParamBase<string[]> {
+    type: "multi-select";
+    options: Array<{
+        label: string;
+        value: string;
+    }>;
+}
+export interface RepoParam extends ParamBase<{
+    repoId: string;
+    branch?: string;
+}> {
+    type: "repo";
+}
+export interface HarnessParam extends ParamBase<{
+    harnessId: string;
+    model?: string;
+}> {
+    type: "harness";
+}
+export interface TemplateParam extends ParamBase<string> {
+    type: "template";
+    templateType: string;
+}
+export interface ResourceParam extends ParamBase<ResourceRef> {
+    type: "resource";
+    resourceType: string;
+}
+export interface JsonParam<T = unknown> extends ParamBase<T> {
+    type: "json";
+}
+export type ParamDescriptor<TValue = unknown> = TextParam | LongTextParam | NumberParam | BooleanParam | SelectParam | MultiSelectParam | RepoParam | HarnessParam | TemplateParam | ResourceParam | JsonParam<TValue>;
+export type ParamObjectSchema = Record<string, ParamDescriptor>;
+export type ParamValue<TDescriptor extends ParamDescriptor> = TDescriptor extends ParamDescriptor<infer V> ? V : never;
+export type ParamsOf<TSchema extends ParamObjectSchema> = {
+    [K in keyof TSchema]: ParamValue<TSchema[K]>;
+};
+export {};

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

@@ -0,0 +1,25 @@
+import type { JsonObject } from "./json";
+export type ResourceRole = "primary" | "context" | "source" | "result";
+export interface ResourceRef {
+    type: string;
+    id: string;
+    projectId?: string;
+    label?: string;
+    extensionId?: string;
+    metadata?: JsonObject;
+}
+export interface ResourceAnchor extends ResourceRef {
+    role?: ResourceRole;
+}
+export interface RepoContext {
+    projectId: string;
+    repoId: string;
+    path: string;
+    remote?: string | null;
+    role?: "default" | "selected" | "workspace";
+}
+export interface PackageAssetDescriptor {
+    kind: "package-asset";
+    path: string;
+    baseUrl: string;
+}

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

@@ -0,0 +1,22 @@
+import type { JsonObject, Struct } from "./json";
+export type UiSlotKind = "menu" | "navigation" | "view" | "settings" | "renderer";
+export interface SlotOptions<TKind extends UiSlotKind = UiSlotKind> {
+    kind: TKind;
+    label?: string;
+    description?: string;
+    metadata?: JsonObject;
+}
+export interface SlotRef<TContext extends Struct = Struct, TKind extends UiSlotKind = UiSlotKind> {
+    id: string;
+    kind: TKind;
+    label?: string;
+    description?: string;
+    metadata?: JsonObject;
+    /** Phantom field used to constrain compatible contributions; never populated at runtime. */
+    context?: TContext;
+}
+export interface SlotInvocationContext<TContext extends Struct = Struct> {
+    id: string;
+    kind: UiSlotKind;
+    context: TContext;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pstdio/sdk",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "repository": {
     "type": "git",
     "url": "https://github.com/pufflyai/prompt-studio"
@@ -25,6 +25,10 @@
       "import": "./dist/client/index.js",
       "types": "./dist/client/index.d.ts"
     },
+    "./extensions": {
+      "import": "./dist/extensions/index.js",
+      "types": "./dist/extensions/index.d.ts"
+    },
     "./plugins": {
       "import": "./dist/plugins/index.js",
       "types": "./dist/plugins/index.d.ts"
@@ -40,7 +44,7 @@
   },
   "scripts": {
     "build": "rm -rf ./dist && bun run build:js && bun run build:types",
-    "build:js": "bun build ./src/api/index.ts ./src/client/index.ts ./src/plugins/index.ts ./src/prompts/index.ts ./src/hooks/index.ts ./src/resources/index.ts --outdir ./dist --root ./src --target node --format esm --packages external",
+    "build:js": "bun build ./src/api/index.ts ./src/client/index.ts ./src/extensions/index.ts ./src/plugins/index.ts ./src/prompts/index.ts ./src/hooks/index.ts ./src/resources/index.ts --outdir ./dist --root ./src --target node --format esm --packages external",
     "build:types": "tsc --project ./tsconfig.build.json",
     "prepack": "bun run build",
     "typecheck": "tsc --noEmit",