@parall/sdk 1.49.0 → 1.50.1

package/src/constants.ts

@@ -377,6 +377,14 @@ export const ENDPOINTS = {
     `${API_BASE}/orgs/${orgId}/members/${memberId}/chats`,
   ORG_MEMBER_TASKS: (orgId: string, memberId: string) =>
     `${API_BASE}/orgs/${orgId}/members/${memberId}/tasks`,
+  // Org-scoped public profile (title / description). GET readable by every
+  // active member; PATCH is CAS-guarded (expected_version).
+  ORG_MEMBER_PROFILE: (orgId: string, userId: string) =>
+    `${API_BASE}/orgs/${orgId}/members/${userId}/profile`,
+  // Private agent Instructions — visibility gated server-side
+  // (agent self + Human org admin/owner). Never cached.
+  AGENT_INSTRUCTIONS: (orgId: string, agentId: string) =>
+    `${API_BASE}/orgs/${orgId}/agents/${agentId}/instructions`,
   REF_SEARCH: (orgId: string) => `${API_BASE}/orgs/${orgId}/refs/search`,
 
   // Direct messages (org-scoped, atomic find-or-create + send)
@@ -814,6 +822,14 @@ export const ENDPOINTS = {
   // Feature flags (org-scoped, server-evaluated)
   FEATURE_FLAGS: (orgId: string) => `${API_BASE}/orgs/${orgId}/feature-flags`,
 
+  // Team templates (org-scoped, owner/admin only)
+  TEMPLATES: (orgId: string) => `${API_BASE}/orgs/${orgId}/templates`,
+  TEMPLATE: (orgId: string, templateId: string) =>
+    `${API_BASE}/orgs/${orgId}/templates/${templateId}`,
+  TEMPLATE_DEPLOYMENTS: (orgId: string) => `${API_BASE}/orgs/${orgId}/template-deployments`,
+  TEMPLATE_DEPLOYMENT: (orgId: string, deploymentId: string) =>
+    `${API_BASE}/orgs/${orgId}/template-deployments/${deploymentId}`,
+
   // Billing & Credits (org-scoped)
   BILLING: (orgId: string) => `${API_BASE}/orgs/${orgId}/billing`,
   BILLING_TRANSACTIONS: (orgId: string) => `${API_BASE}/orgs/${orgId}/billing/transactions`,

package/src/index.ts

@@ -1,12 +1,13 @@
-export * from './types.js';
-export * from './constants.js';
-export { ParallClient, ApiError } from './client.js';
+export * from './browser-viewer.js';
 export type { ParallClientOptions } from './client.js';
-export { ParallWs } from './ws.js';
+export { ApiError, ParallClient } from './client.js';
+export * from './constants.js';
+export * from './types.js';
 export type {
   ParallWsOptions,
+  WsClientEventMap,
   WsConnectionState,
-  WsEventType,
   WsEventHandler,
-  WsClientEventMap,
+  WsEventType,
 } from './ws.js';
+export { ParallWs } from './ws.js';

package/src/types.ts

@@ -138,6 +138,38 @@ export type MessageType =
 
 export const MENTION_ALL_USER_ID = 'all';
 
+/**
+ * Member-type-filtered variants of the @all broadcast mention (group chats
+ * only): identical notification semantics, recipient set limited to human /
+ * agent members respectively.
+ */
+export const MENTION_ALL_HUMANS_USER_ID = 'allhuman';
+export const MENTION_ALL_AGENTS_USER_ID = 'allagent';
+
+/** True when a mention user_id is a broadcast token rather than a usr_ id. */
+export function isBroadcastMentionId(userId: string): boolean {
+  return (
+    userId === MENTION_ALL_USER_ID ||
+    userId === MENTION_ALL_HUMANS_USER_ID ||
+    userId === MENTION_ALL_AGENTS_USER_ID
+  );
+}
+
+/**
+ * True when a mention user_id addresses the given viewer — either their own
+ * usr_ id, @all, or the typed broadcast matching their user type.
+ */
+export function mentionTargetsUser(
+  mentionUserId: string,
+  userId: string,
+  userType: UserType,
+): boolean {
+  if (mentionUserId === userId || mentionUserId === MENTION_ALL_USER_ID) return true;
+  if (mentionUserId === MENTION_ALL_HUMANS_USER_ID) return userType === 'human';
+  if (mentionUserId === MENTION_ALL_AGENTS_USER_ID) return userType === 'agent';
+  return false;
+}
+
 export interface Mention {
   user_id: string;
   offset: number;
@@ -401,9 +433,48 @@ export interface OrgMember {
   user_id: string;
   role: OrgMemberRole;
   joined_at: string;
+  // Org-scoped public profile projection. Missing profile row reads as
+  // empty strings with profile_version 0.
+  title: string;
+  description: string;
+  profile_version: number;
   user?: User;
 }
 
+// Org-scoped public member profile (Human and Agent alike). Never carries
+// private agent Instructions.
+export interface MemberProfile {
+  user_id: string;
+  display_name: string;
+  type: UserType;
+  title: string;
+  description: string;
+  profile_version: number;
+}
+
+// Full-replacement update over {title, description} with a version CAS.
+// expected_version 0 = first write (no profile row yet). A stale version
+// gets 409 PROFILE_VERSION_CONFLICT with error.details.current_version.
+export interface UpdateMemberProfileRequest {
+  title: string;
+  description: string;
+  expected_version: number;
+}
+
+// Private agent Instructions — org-admin maintained runtime context.
+export interface AgentInstructions {
+  agent_user_id: string;
+  instructions: string;
+  version: number;
+  updated_at?: string;
+  updated_by?: string;
+}
+
+export interface UpdateAgentInstructionsRequest {
+  instructions: string;
+  expected_version: number;
+}
+
 // Team — a named group of org members, referenced in wiki ACLs as `@slug`.
 export interface Team {
   id: string;
@@ -561,6 +632,159 @@ export interface FeatureFlagsResponse {
   flags: Record<string, boolean | string | number>;
 }
 
+// ============================================================
+// Team Template Types
+// ============================================================
+
+export type TemplateParameterInputType = 'text' | 'select' | 'multi';
+export type TemplateParameterValue = string | string[];
+
+export interface TemplateParameter {
+  key: string;
+  label: string;
+  input_type: TemplateParameterInputType;
+  options?: string[];
+  default?: TemplateParameterValue;
+  required?: boolean;
+}
+
+export interface TemplateDependency {
+  type: 'clip';
+  ref: string;
+  required?: boolean;
+  degraded_note?: string;
+}
+
+export interface TemplateAgentPublicProfile {
+  title: string;
+  description: string;
+}
+
+export interface TemplateAgentSpec {
+  key: string;
+  display_name: string;
+  public_profile: TemplateAgentPublicProfile;
+  instructions: string;
+  runtime_type?: string;
+  model?: string | null;
+  compute?: {
+    machine_type: 'cloud';
+    machine_label?: string;
+  } | null;
+  dependencies?: TemplateDependency[];
+}
+
+export interface TemplateWorkspaceScaffold {
+  channels: Array<{
+    purpose?: string;
+    name_pattern: string;
+  }>;
+  schedules?: Array<{
+    agent_key: string;
+    name: string;
+    cron: string;
+    description: string;
+  }>;
+  project?: {
+    name_pattern: string;
+  } | null;
+}
+
+export interface TemplateDefinition {
+  name: string;
+  mission: string;
+  scope_tags?: string[];
+  outcomes?: string[];
+  agents: TemplateAgentSpec[];
+  workspace_scaffold: TemplateWorkspaceScaffold;
+  parameters?: TemplateParameter[];
+}
+
+// Explicit organization catalog projection. It intentionally does not extend
+// the authoring types: future authoring fields must never become public by
+// inheritance. Instructions, runtime/model/compute, and workspace seed data
+// stay on the cluster-internal CRUD and server-side deployment path.
+export interface TemplateCatalogAgentSpec {
+  key: string;
+  display_name: string;
+  public_profile: TemplateAgentPublicProfile;
+  dependencies?: Array<Pick<TemplateDependency, 'type' | 'ref' | 'required'>>;
+}
+
+export interface TemplateCatalogDefinition {
+  name: string;
+  mission: string;
+  scope_tags?: string[];
+  outcomes?: string[];
+  agents: TemplateCatalogAgentSpec[];
+  parameters?: TemplateParameter[];
+}
+
+// Resolved in the target organization at catalog-read time. This is not part
+// of the persisted authoring definition and carries no readiness/connection
+// state.
+export interface TemplateDependencyMetadata {
+  type: 'clip';
+  ref: string;
+  display_name: string;
+}
+
+export interface Template {
+  id: string;
+  version: string;
+  /** Opaque token pinning the version + exact definition shown to the user. */
+  revision: string;
+  name: string;
+  definition: TemplateCatalogDefinition;
+  dependency_metadata?: TemplateDependencyMetadata[];
+  status: 'active' | 'archived';
+  created_at: string;
+  updated_at: string;
+}
+
+export interface DeployTemplateRequest {
+  template_id: string;
+  template_revision: string;
+  parameter_values?: Record<string, TemplateParameterValue>;
+}
+
+export type TemplateDeploymentAgentState = 'up' | 'provisioning' | 'error';
+
+export interface TemplateDeploymentReport {
+  deployment_id: string;
+  status: 'deployed';
+  team: {
+    name: string;
+    main_chat_id: string;
+  };
+  agents: Array<{
+    key: string;
+    agent_id: string;
+    display_name: string;
+    public_profile: TemplateAgentPublicProfile;
+    runtime: string;
+    state: TemplateDeploymentAgentState;
+  }>;
+  resources: {
+    chats: Array<{ id: string; name: string }>;
+    schedules: Array<{ id: string; name: string }>;
+    project_id?: string;
+  };
+  dependencies: Array<{
+    type: 'clip';
+    ref: string;
+    name?: string;
+    required: boolean;
+    connected: boolean;
+    declared_by: string[];
+  }>;
+  kickoff: {
+    sent: boolean;
+    message_id?: string;
+    error?: string;
+  };
+}
+
 // ============================================================
 // API Request Types
 // ============================================================
@@ -699,6 +923,9 @@ export interface CreateAgentRequest {
   thinking_effort?: string; // model-dependent: "minimal" | "low" | "medium" | "high" | "xhigh" | "max"
   agent_permissions?: string[];
   runtime_type?: string; // "openclaw" | "claude-code" | "codex"; default "openclaw"
+  // Preferred write field for the agent's private instruction text.
+  instructions?: string;
+  /** @deprecated Same-value alias of `instructions`; loses when both are set. */
   description?: string;
   machine_type?: string;
   machine_label?: string; // preset: "lite" | "standard" | "pro" | "custom"
@@ -795,6 +1022,9 @@ export interface UpdateAgentRequest {
   agent_model?: string;
   model_management?: string;
   agent_permissions?: string[];
+  // Preferred write field for the agent's private instruction text.
+  instructions?: string;
+  /** @deprecated Same-value alias of `instructions`; loses when both are set. */
   description?: string;
   thinking_effort?: string;
 }
@@ -952,7 +1182,18 @@ export interface AgentProfile {
   machine_id: string | null;
   hosting_mode?: 'hosted' | 'self_hosted' | 'platform_runtime';
   runtime_type: string;
+  /**
+   * @deprecated Alias of `instructions` kept for pre-rename readers; the
+   * server keeps both byte-identical. Use `instructions` (and the
+   * dedicated instructions endpoints) instead.
+   */
   description: string | null;
+  // Private Instructions (admin-maintained runtime context). Redacted for
+  // non-admin viewers on list surfaces, same as description.
+  instructions?: string | null;
+  instructions_version?: number;
+  instructions_updated_at?: string | null;
+  instructions_updated_by?: string | null;
   thinking_effort: string | null;
   run_config?: RunConfig;
   created_by: string;
@@ -972,6 +1213,10 @@ export interface AgentPresence {
 
 export interface AgentWithRuntime extends User {
   agent_profile?: AgentProfile | null;
+  // Org-scoped public profile (title / public description) for the org the
+  // request is scoped to. Runtimes read it from /agents/me to build the
+  // public identity prompt section.
+  public_profile?: MemberProfile | null;
   machine?: Machine | null;
   presence?: AgentPresence | null;
 }
@@ -1098,6 +1343,12 @@ export interface MachineBrowserProfileViewerData {
   turn?: { url: string; username?: string; credential?: string };
 }
 
+/** Daemon reply body for one machine.browser_profile.viewer request. */
+export interface MachineBrowserProfileViewerResponse {
+  result?: Record<string, unknown>;
+  error?: { code?: string; message: string };
+}
+
 export interface AgentNewSessionData {
   previous_session_id?: string;
 }