Multiplayer agent harness for work.
import type { TeamStore } from "../teams/teams.ts";
import type { ExternalSlackPolicies } from "../resolution/external-slack.ts";
import type { Mailer } from "../../plugins/chassis/src/resend.ts";
import type { DeploymentInvitation } from "../deploy/email-access.ts";
import type { AdmittedWork } from "../util/admitted-work.ts";
import type { EventBus } from "../util/event-bus.ts";
import type { RunStreamEvent } from "../runs/run-stream-events.ts";
import type { ResourceSearchStore, ResourceSearchHit } from "../search/resource-search.ts";
import type { ModelOverlayStore } from "../model/model-overlay-store.ts";
import type { SwarmService } from "../swarms/swarm-service.ts";
import type {
DeliveryProvenance,
Grant,
PendingApproval,
PendingApprovalRecord,
Permission,
Principal,
ScopeId,
Session,
SessionEntry,
TurnRequest,
TurnResult,
TurnRuntime,
} from "../types.ts";
import type { OutgoingAttachment } from "../types.ts";
import type { SecurityScreenProbe } from "../security/security-screener.ts";
import type { Readable } from "node:stream";
import { type FileArtifact, type FileArtifactStore, type ListOwnedOptions } from "../files/file-artifact-store.ts";
import type { IdentityService } from "../identity/identity-service.ts";
import type { SessionStore, TranscriptEntry } from "../sessions/session-store.ts";
import { type Sandbox } from "../sandbox/sandbox.ts";
import type { ProcessRegistry } from "../processes/process-registry.ts";
import type { MonitorStore } from "../monitors/monitor-store.ts";
import type { EngagedRegistry } from "../wake/engaged-registry.ts";
import type { Orchestrator } from "../core/orchestrator.ts";
import type { Run, RunDeliveryState, RunStore } from "../runs/run-store.ts";
import type { GoalView, ReasoningBlock, TurnStream } from "../runs/turn-stream.ts";
import type { SessionStateBus, SessionStateEvent } from "../runs/session-state-bus.ts";
import type { LedgerEventBus, OwnedLedgerEvent } from "../loops/ledger-events.ts";
import type { SubscribeOptions } from "../util/event-bus.ts";
import type { RunActivityEntry, RunActivityStore } from "../runs/run-activity-store.ts";
import type { RunSignal, RunSignalStore } from "../runs/run-signal-store.ts";
import type { ModelGateway } from "../model/model-gateway.ts";
import type { ModelCredentialStore } from "../model/model-credential-store.ts";
import type { UserModelCredentialStore } from "../model/user-model-credential-store.ts";
import type { CustomProviderStore } from "../model/custom-provider-store.ts";
import type { McpServerStore } from "../mcp/mcp-server-store.ts";
import type { McpToolService } from "../mcp/mcp-tool-service.ts";
import type { AclStore } from "../acl/acl-store.ts";
import type { SkillStore, Skill, SkillResolution } from "../skills/skill-store.ts";
import type { SkillPack, NewSkillPack, SkillPackStore } from "../skills/skill-pack-store.ts";
import type { SkillPackFetcher } from "../skills/pack-fetcher.ts";
import { type IngestPlan, type ImportResult } from "../skills/ingest.ts";
import { type SkillBundleStore } from "../skills/skill-bundle-store.ts";
import type { AuditLog } from "../audit/audit-log.ts";
import type { CapabilityClaims } from "../auth/capability-token.ts";
import type { ScopedConfigStore } from "../resolution/config-store.ts";
import { type AdminService } from "../admin/admin-service.ts";
import type { CronStore, CreateCronInput, CronPatch } from "../cron/cron-store.ts";
import type { CronFireRecord } from "../cron/fire-store.ts";
import type { WebhookStore, WebhookEvent, CreateWebhookInput } from "../webhooks/webhook-store.ts";
import type { DeliveryStore } from "../delivery/delivery-store.ts";
import type {
ChannelMembership,
ChannelResolution,
DirectoryChannel,
DirectoryMember,
DirectoryMeta,
DirectoryStore,
GroupMembership,
RecipientResolution,
} from "../directory/directory-store.ts";
import type {
Cron,
CronFireLogEntry,
CronFireNote,
Delivery,
Destination,
SurfaceContextQuery,
SurfaceContextRequest,
SurfaceContextResult,
Webhook,
} from "../types.ts";
import type {
ActiveThread,
CachedMessage,
ContainerSummary,
IngestEvent,
ReadMessagesOpts,
SearchOpts,
SurfaceCache,
} from "../surface-cache/surface-cache.ts";
import { type BotPolicy, type ChannelPolicy, type ChannelPolicyStore } from "../surface-cache/channel-policy-store.ts";
import { type AmbientDecision } from "../surface-cache/ambient-judge.ts";
import type { AmbientJudgmentStore } from "../surface-cache/ambient-judgment-store.ts";
import type { AckEmojiPickStore } from "../surface-cache/ack-emoji-pick-store.ts";
import type { Deployment } from "../deploy/deploy-store.ts";
import type { DeploymentLayerRuntime } from "../deployment/load-layer.ts";
import { type ArtifactHome, type ArtifactType } from "./artifact-share.ts";
import type {
DeployService,
DeployInput,
RedeployInput,
Reach,
ReachOptions,
DeploymentGrantee,
} from "../deploy/deploy-service.ts";
import { type DurableMap } from "../persistence/durable-map.ts";
import type { AdvisoryLock } from "../persistence/advisory-lock.ts";
import type { Environment, EnvironmentAttachment, EnvironmentStore } from "../environments/environment-store.ts";
import type { ModelProviderAvailability } from "../model/pi-models.ts";
import type { RuntimeChoice } from "../harness/harness.ts";
import { type ReachOpts, type ReachResolution, type ReachTarget } from "../reach/reach.ts";
import { type Project, type ProjectStore } from "../projects/project-store.ts";
import type { SearchHit } from "../search/core-search.ts";
interface DeploymentVersionView {
version: number;
createdAt: number;
commit?: string;
parentCommit?: string;
}
export interface DeploymentView {
id: string;
ownerScopeId: ScopeId;
createdBy: string;
createdInScope?: ScopeId;
name?: string;
displayName?: string;
currentVersion: number;
appliedVersion?: number;
status: Deployment["status"];
alwaysOn?: boolean;
embedAncestors?: string[];
public: boolean;
lastAccessAt?: number;
createdAt?: number;
updatedAt?: number;
versions: DeploymentVersionView[];
}
export interface ViewerDeployment extends DeploymentView {
permission: Permission;
}
export function deploymentView(d: Deployment): DeploymentView {
const versions = d.versions.map(({ version, createdAt, commit, parentCommit }) => ({
version,
createdAt,
...(commit ? { commit } : {}),
...(parentCommit ? { parentCommit } : {}),
}));
return {
id: d.id,
ownerScopeId: d.ownerScopeId,
createdBy: d.createdBy,
...(d.createdInScope ? { createdInScope: d.createdInScope } : {}),
...(d.name ? { name: d.name } : {}),
...(d.displayName ? { displayName: d.displayName } : {}),
currentVersion: d.currentVersion,
...(d.appliedVersion !== undefined ? { appliedVersion: d.appliedVersion } : {}),
status: d.status,
...(d.alwaysOn ? { alwaysOn: true } : {}),
...(d.embedAncestors?.length ? { embedAncestors: d.embedAncestors } : {}),
public: d.public === true,
...(d.lastAccessAt !== undefined ? { lastAccessAt: d.lastAccessAt } : {}),
...(versions[0] ? { createdAt: versions[0].createdAt } : {}),
...(versions.at(-1) ? { updatedAt: versions.at(-1)!.createdAt } : {}),
versions,
};
}
interface ReachNowInput {
senderId: string;
senderScope: ScopeId;
text?: string;
recipient?: string;
channel?: string;
participants?: readonly string[];
threadTs?: string;
unfurlLinks?: boolean;
attachments?: OutgoingAttachment[];
react?: { messageTs: string; emoji: string };
delete?: { messageTs: string };
currentDestination?: Destination;
}
export type ReachNowResult =
| {
ok: true;
delivery: Delivery;
recipient?: { principalId: string; displayName: string };
channel?: { channelId: string; name: string };
group?: { groupId: string };
}
| {
ok: false;
status: 400 | 403 | 404 | 409 | 502;
error: string;
message: string;
candidates?: Array<Record<string, string>>;
};
export type VisibleCron = Cron & { scopeName?: string };
export type ProjectView = Project & {
scopeId: ScopeId;
members: Array<{ principalId: string; displayName: string; avatarUrl?: string; viaChannel?: boolean }>;
};
type ProjectViewMutation =
| { status: "ok"; project: ProjectView; changed: boolean }
| { status: "not_found" | "forbidden" | "invalid_member" | "invalid_name" | "invalid_channel" | "channel_in_use" };
interface DeploymentGitUrl {
url: string;
permission: "read" | "write";
}
interface SessionBackgroundView {
jobs: Array<{ processId: string; command: string; purpose?: string; startedAt: number; expiresAt: number }>;
watches: Array<{
id: string;
processId: string;
command: string;
pattern?: string;
instructions?: string;
createdAt: number;
expiresAt: number;
lastFiredAt?: number;
}>;
crons: Array<{
id: string;
title?: string;
nextFireAt?: number;
lastFire?: { firedAt: number; status?: CronFireLogEntry["status"] };
}>;
}
interface SessionBackgroundOutput {
chunk: string;
cursor: number;
state: "running" | "exited";
exitCode?: number;
}
interface TranscriptWindow {
tailTurns?: number;
sinceSeq?: number;
beforeSeq?: number;
}
export interface SessionPinView {
id: string;
text?: string;
entrySeq?: number;
preview?: string;
addedBy: string;
createdAt: number;
}
type PinItemResult = { pin: SessionPinView } | { error: "not_found" | "bad_entry" | "limit" };
export interface SessionSearchHit {
sessionId: string;
title: string | null;
scopeId: string;
channelName?: string;
surface?: string;
seq: number;
entryType: string;
author?: string;
snippet: string;
createdAt: number;
archived?: boolean;
}
export interface App {
swarms?: SwarmService;
turn(req: TurnRequest, replay?: { signalDedupKey: string }): Promise<TurnResult>;
getApproval(requestId: string, viewer?: string): Promise<(PendingApprovalRecord & { requestId: string }) | null>;
subscribeSessionStates(cb: (event: SessionStateEvent) => void, opts?: SubscribeOptions): () => void;
subscribeLedgerEvents(cb: (event: OwnedLedgerEvent) => void, opts?: SubscribeOptions): () => void;
listSessionApprovals(sessionId: string, viewer: string): Promise<PendingApproval[]>;
pendingApprovalForThread(threadRef: string, viewer?: string): Promise<TurnResult | null>;
subscribeRun(runId: string, listener: (event: RunStreamEvent) => void, onResync?: () => void): () => void;
syncRunStream(runId: string, offset: number, reasoning: Record<string, number>): void;
getRun(
runId: string,
viewer?: string,
): Promise<{
status: Run["status"];
attempt: number;
result: TurnResult | null;
input?: {
runId: string;
seq: number | null;
text: string;
createdAt: number;
attachments?: Array<{ name: string; mimetype: string; sizeBytes: number }>;
};
goal?: GoalView;
runtime?: TurnRuntime;
partial?: string;
partialStartOffset?: number;
alive?: boolean;
stale?: boolean;
replying?: boolean;
replyComplete?: boolean;
firstBlock?: string;
firstBlockClosed?: boolean;
surfacePosted?: boolean;
activity?: RunActivityEntry[];
reasoning?: ReasoningBlock[];
startedAt: number | null;
finishedAt: number | null;
} | null>;
getRunToolEntries(runId: string, viewer?: string, afterSeq?: number): Promise<SessionEntry[]>;
stopConversation(threadRef: string, viewer?: string): Promise<boolean>;
activeRunForThread(
threadRef: string,
viewer?: string,
): Promise<{ runId: string; queued?: Array<{ runId: string; text: string; hasAttachments?: boolean }> } | null>;
editQueuedRun(
runId: string,
text: string,
expectedText: string,
viewer?: string,
): Promise<{ edited: boolean; reason?: string }>;
withdrawRun(runId: string, viewer?: string): Promise<{ withdrawn: boolean; reason?: string }>;
signalRun(
runId: string,
signal: RunSignal,
viewer?: string,
): Promise<{ accepted: boolean; reason?: string; replayed?: boolean }>;
replayOrphanedRunSignals(runId: string): Promise<void>;
getSession(
sessionId: string,
window?: TranscriptWindow,
): Promise<{ session: Session; entries: TranscriptEntry[]; earlierEntries?: number; pins?: SessionPinView[] } | null>;
getSessionForViewer(
sessionId: string,
principalId: string,
window?: TranscriptWindow,
): Promise<{
session: Session;
entries: TranscriptEntry[];
earlierEntries?: number;
pins?: SessionPinView[];
goal?: GoalView;
runtime?: TurnRuntime;
} | null>;
canViewSessionSnapshot(
sessionId: string,
principalId: string,
visibility: { minSeq: number; maxSeq: number; minCreatedAt: number; maxCreatedAt: number },
): Promise<boolean>;
getSessionEntryForViewer(
sessionId: string,
principalId: string,
seq: number,
): Promise<{ entry: SessionEntry } | null>;
pinConversationItem(
threadRef: string,
addedBy: string,
pin: { text?: string; entrySeq?: number },
): Promise<PinItemResult>;
listConversationPins(threadRef: string, reader: string): Promise<SessionPinView[] | null>;
unpinConversationItem(threadRef: string, pinId: string): Promise<boolean | null>;
listSessions(principalId: string): Promise<Session[]>;
listSessionPage(principalId: string, query: SessionPageQuery): Promise<SessionPageResult>;
sessionChildren(principalId: string, sessionId: string): Promise<Session[] | null>;
sessionRow(principalId: string, ref: { id?: string; threadRef?: string }): Promise<Session | null>;
searchResources(
principalId: string,
query: string,
): Promise<{ hits: ResourceSearchHit[]; failed: string[]; limited: string[] }>;
searchConversations: App["search"];
searchSessions(principalId: string, query: string, limit?: number): Promise<SessionSearchHit[]>;
search(
query: string,
principals: readonly Principal[],
limit?: number,
): Promise<{ hits: SearchHit[]; failedBackends: string[] }>;
sessionBackground(sessionId: string, viewer: string): Promise<SessionBackgroundView | null>;
readSessionBackgroundOutput(
sessionId: string,
processId: string,
viewer: string,
sinceCursor: number,
): Promise<SessionBackgroundOutput | null>;
listContexts(principalId: string): Promise<ContextSummary[]>;
listProjects(principalId: string): Promise<ProjectView[]>;
createProject(principalId: string, name: string): Promise<ProjectView | null>;
addProjectMember(id: string, principalId: string, memberId: string): Promise<ProjectViewMutation>;
removeProjectMember(id: string, principalId: string, memberId: string): Promise<ProjectViewMutation>;
setProjectSlackChannel(id: string, principalId: string, channel: string | null): Promise<ProjectViewMutation>;
renameProject(id: string, principalId: string, name: string): Promise<ProjectViewMutation>;
updateSession(
sessionId: string,
principalId: string,
patch: {
title?: string | null;
archived?: boolean;
pinned?: boolean;
color?: string | null;
readAt?: number;
},
): Promise<Session | null>;
regenerateTitle(sessionId: string, principalId: string): Promise<{ title: string | null } | null>;
detachSession(sessionId: string, principalId: string): Promise<{ detached: true } | null>;
cancelSessionGoal(
sessionId: string,
principalId: string,
): Promise<{ cancelled: true } | { cancelled: false; reason: "no_open_goal" | "busy" } | null>;
spawnSession(principalId: string, opts: { scopeId: ScopeId; title?: string }): Promise<{ session: Session } | null>;
discardSession(sessionId: string, principalId: string): Promise<boolean>;
forkSession(
sessionId: string,
principalId: string,
opts?: { upToSeq?: number },
): Promise<{ session: Session; entries: SessionEntry[] } | null>;
listFilesForViewer(principalId: string, opts?: ListOwnedOptions, inScope?: ScopeId): Promise<FileListPage>;
uploadFileForViewer(
principalId: string,
input: { scopeId?: ScopeId; name: string; mimetype?: string; data: AsyncIterable<Uint8Array> },
): Promise<FileListItem | null>;
listScopeResources(principalId: string, scope: ScopeId): Promise<ScopeResources | null>;
managesScope(principalId: string, scope: ScopeId): Promise<boolean>;
currentScopeMembers(scope: ScopeId): Promise<Principal[] | undefined>;
isCurrentSharedScopeMember(principalId: string, scope: ScopeId): Promise<boolean>;
isOpenScopeMember(principalId: string, scope: ScopeId): Promise<boolean>;
membershipControlsScope(scope: ScopeId): Promise<boolean>;
authorizesCapabilityScope(
claims: Pick<CapabilityClaims, "actorId" | "scopeId" | "scopeVersion" | "botActor" | "liveActor" | "members">,
): Promise<boolean>;
openFileForViewer(id: string, principalId: string): Promise<OpenedFile | null>;
grant(g: Grant): Promise<void>;
revokeGrant(ownerScopeId: ScopeId, ref: string, granteeScopeId: ScopeId, revokedBy: string): Promise<void>;
promoteSkill(id: string, targetScopeId: ScopeId, actorId: string, liveActor: boolean): Promise<Skill>;
belongsToScope(principalId: string, scope: ScopeId): Promise<boolean>;
canManageArtifactHome(homeScopeId: ScopeId, createdBy: string, principalId: string): Promise<boolean>;
artifactGrantPermission(ownerScopeId: ScopeId, ref: string, principalId: string): Promise<Permission | null>;
getArtifactHome(type: ArtifactType, idOrName: string): Promise<ArtifactHome | null>;
moveArtifactHome(type: ArtifactType, id: string, toScope: ScopeId, movedBy: string): Promise<void>;
getSoul(scopeId: ScopeId): {
scopeId: ScopeId;
soul: string | null;
soulVersion: number;
orgScopeId: ScopeId;
orgSoul: string | null;
orgSoulVersion: number;
effectiveSoul: string;
};
updateSoul(
scopeId: ScopeId,
content: string,
actorId: string,
opts?: { allowSharedScope?: boolean; expectedVersion?: number },
): Promise<number>;
createCron(input: CreateCronInput): Promise<Cron>;
getCron(id: string): Promise<Cron | null>;
listCrons(): Promise<Cron[]>;
listCronsForViewer(principalId: string): Promise<{ owned: Cron[]; visible: VisibleCron[] }>;
updateCron(id: string, patch: CronPatch): Promise<Cron | null>;
deleteCron(id: string): Promise<void>;
setCronEnabled(id: string, enabled: boolean): Promise<void>;
setCronFireNote(id: string, note: CronFireNote): Promise<"applied" | "superseded" | "missing">;
listCronFires(id: string, opts?: { limit?: number }): Promise<{ runs: CronFireLogEntry[]; total: number }>;
cronFiresByThreadRefs(threadRefs: readonly string[]): Promise<CronFireRecord[]>;
latestCronFireForThread(id: string, threadRef: string): Promise<CronFireLogEntry | undefined>;
setCronRuntime(id: string, runtime: Exclude<Cron["runtime"], undefined>): Promise<Cron | null>;
setCronDestination(id: string, destination: Destination | undefined): Promise<Cron | null>;
createWebhook(input: CreateWebhookInput): Promise<Webhook>;
getWebhook(id: string): Promise<Webhook | null>;
listWebhookEvents(id: string, viewer: string): Promise<Array<WebhookEvent & { sessionId?: string }>>;
listWebhooks(): Promise<Webhook[]>;
setWebhookEnabled(id: string, enabled: boolean): Promise<void>;
updateWebhook(id: string, patch: { action: string }): Promise<Webhook | null>;
pendingDeliveries(type: string, claimMs?: number): Promise<Delivery[]>;
enqueueDelivery(input: {
destination: Destination;
text: string;
idempotencyKey: string;
provenance?: DeliveryProvenance;
}): Promise<void>;
createContextRequest(source: string, query: SurfaceContextQuery): Promise<SurfaceContextRequest>;
getContextRequest(id: string): Promise<SurfaceContextRequest | null>;
deleteContextRequest(id: string): Promise<void>;
pendingContextRequests(source: string): Promise<SurfaceContextRequest[]>;
fulfillContextRequest(id: string, outcome: { result?: SurfaceContextResult; error?: string }): Promise<boolean>;
onContextRequestCreated(listener: (request: SurfaceContextRequest) => void): () => void;
ingestSurfaceEvents(
events: IngestEvent[],
surface?: string,
self?: { name?: string; mentionId?: string },
): Promise<{ upserted: number }>;
searchSurface(query: string, opts?: SearchOpts): Promise<CachedMessage[]>;
readSurfaceMessages(container: string, opts?: ReadMessagesOpts): Promise<CachedMessage[]>;
activeSurfaceThreads(opts?: { container?: string; limit?: number }): Promise<ActiveThread[]>;
listSurfaceContainers(opts?: { limit?: number }): Promise<ContainerSummary[]>;
getChannelPolicy(container: string): Promise<ChannelPolicy | null>;
setChannelPolicy(
container: string,
orders: string,
setBy?: string,
bots?: Record<string, BotPolicy>,
sessionId?: string,
ambientEnabled?: boolean | null,
): Promise<ChannelPolicy | null>;
judgeAmbientContainer(
surface: string,
container: string,
opts?: { reason?: "messages" | "scheduled" },
): Promise<AmbientDecision>;
ackDelivery(id: string, slackApiMs?: number): Promise<void>;
ackDeliveryByKey(idempotencyKey: string): Promise<void>;
setRunDeliveryState(runId: string, state: RunDeliveryState): Promise<boolean>;
upsertDirectory(members: DirectoryMember[], syncedAt?: number): Promise<boolean>;
upsertChannels(
channels: DirectoryChannel[],
channelMembers?: ChannelMembership[],
syncedAt?: number,
channelRosterIds?: string[],
revocations?: ChannelMembership[],
partial?: boolean,
): Promise<boolean>;
upsertGroups(
groupMembers: GroupMembership[],
syncedAt?: number,
groupIds?: string[],
groupRosterIds?: string[],
): Promise<boolean>;
setDirectoryWorkspaceUrl(url: string): Promise<void>;
directoryMeta(): Promise<DirectoryMeta>;
resolveRecipient(query: string): Promise<RecipientResolution>;
resolveChannel(query: string): Promise<ChannelResolution>;
directoryMember(principalId: string): Promise<DirectoryMember | null>;
samePerson(a: string, b: string): Promise<boolean>;
personMatcher(actorId: string): Promise<(id: string) => Promise<boolean>>;
cronAdminUrl(cron: Cron): string | undefined;
channelName(channelId: string): Promise<string | undefined>;
ambientJudge?(systemPrompt: string, prompt: string): Promise<string | undefined>;
directoryMembers(): Promise<DirectoryMember[]>;
directoryChannels(): Promise<DirectoryChannel[]>;
channelMember(channelId: string, principalId: string): Promise<boolean>;
channelVisibleTo(actorId: string, channelId: string, isPrivate?: boolean): Promise<boolean>;
recordPrincipalDelivery(deliveryId: string, recipientThreadRef: string): Promise<void>;
reachNow(input: ReachNowInput): Promise<ReachNowResult>;
resolveReachTarget(target: ReachTarget, authorityId: string, opts?: ReachOpts): Promise<ReachResolution>;
deploy(input: DeployInput): Promise<Deployment>;
redeploy(id: string, input: RedeployInput): Promise<Deployment>;
listDeployments(): Promise<Deployment[]>;
getDeployment(idOrName: string): Promise<Deployment | null>;
listDeploymentsForViewer(principalId: string): Promise<ViewerDeployment[]>;
effectiveDeploymentPermission(d: Deployment, principalId: string): Promise<Permission | null>;
deploymentGitPermissionFor(idOrName: string, principalId: string): Promise<"read" | "write" | null>;
listSkills(): Promise<Skill[]>;
getSkill(id: string): Promise<Skill | null>;
archiveSkill(id: string): Promise<Skill>;
listVisibleSkills(principalId: string): Promise<SkillResolution[]>;
canManageSkill(skill: Skill, principalId: string): Promise<boolean>;
updateOwnedSkill(
id: string,
principalId: string,
patch: { description?: string; body?: string },
opts?: { liveActor?: boolean },
): Promise<Skill | "trigger_blocked" | null>;
restoreOwnedSkill(id: string, principalId: string): Promise<Skill | null>;
listSkillPacks(): Promise<SkillPack[]>;
getSkillPack(id: string): Promise<SkillPack | null>;
registerSkillPack(input: NewSkillPack): Promise<SkillPack>;
updateSkillPack(id: string, patch: Partial<Omit<SkillPack, "id" | "createdAt">>): Promise<SkillPack>;
skillPackCatalog(id: string): Promise<IngestPlan & { bundlePaths: string[] }>;
importSkillPack(id: string, selected: "all" | string[], scopeIds?: ScopeId[]): Promise<ImportResult>;
syncSkillPack(id: string): Promise<ImportResult>;
removeSkillPack(id: string): Promise<{ removed: number }>;
createOwnedSkill(input: {
principalId: string;
homeScope?: ScopeId;
name: string;
description: string;
body: string;
requiredCapabilities?: string[];
}): Promise<Skill | null>;
deleteOwnedSkill(input: {
principalId: string;
id: string;
liveActor?: boolean;
}): Promise<"missing" | "forbidden" | "trigger_blocked" | "deleted">;
rollbackDeployment(id: string, version: number): Promise<void>;
archiveDeployment(id: string): Promise<void>;
restoreDeployment(id: string, actorId?: string): Promise<Deployment>;
canManageDeployment(idOrName: string, callerId: string, actingScopeId?: ScopeId): Promise<boolean>;
renameDeployment(id: string, name: string): Promise<Deployment>;
setDeploymentDisplayName(id: string, displayName: string): Promise<Deployment>;
setDeploymentAlwaysOn(id: string, alwaysOn: boolean): Promise<Deployment>;
setDeploymentEmbedAncestors(id: string, embedAncestors: string[]): Promise<Deployment>;
setDeploymentPublic(idOrName: string, isPublic: boolean, actor: { createdBy: string }): Promise<Deployment>;
maintainDeployments(): Promise<number>;
reachDeployment(id: string, principalId: string, opts?: ReachOptions): Promise<Reach>;
deploymentLogsFor(
id: string,
principalId: string,
opts: { tailLines: number },
): Promise<{ status: "ok"; logs: string | null } | { status: "not_found" | "denied" }>;
shareDeployment(
idOrName: string,
grantee: ScopeId,
permission: Permission | null,
actor: { createdBy: string },
): Promise<DeploymentGrantee[]>;
inviteToDeployment(
idOrName: string,
email: string,
actorId: string,
): Promise<{
grantees: DeploymentGrantee[];
invitation: DeploymentInvitation;
}>;
deploymentGrantees(idOrName: string): Promise<DeploymentGrantee[]>;
deploymentGitRepoPath(id: string): Promise<string | null>;
runDeploymentGitPush<T>(id: string, runReceivePack: () => Promise<{ result: T; ok: boolean }>): Promise<T>;
deploymentGitUrlFor(
idOrName: string,
principalId: string,
opts: { secret: string; baseUrl: string; ttlMs?: number },
): Promise<DeploymentGitUrl | null>;
authorizesDeploymentGitAccess(id: string, principalId: string, permission: "read" | "write"): Promise<boolean>;
reapIdleDeployments(ttlMs: number, now?: number): Promise<number>;
listEnvironments(): Promise<{ environment: Environment; attachments: EnvironmentAttachment[] }[]>;
createEnvironment(input: { scopeId: ScopeId; name: string; actorId: string }): Promise<Environment>;
resolveEnvironmentByName(name: string): Promise<Environment | null>;
attachScope(input: { scopeId: ScopeId; environmentId: string; actorId: string }): Promise<void>;
}
export interface AppDeps {
externalSlackPolicies?: ExternalSlackPolicies;
admittedWork?: AdmittedWork;
shutdown?: () => AbortSignal;
resourceSearch?: ResourceSearchStore;
swarms?: SwarmService;
identity: IdentityService;
publicWebUrl?: string;
inviteMailer?: Mailer;
sessions: SessionStore;
screenSecurity?: SecurityScreenProbe;
orchestrator: Orchestrator;
runs: RunStore;
leaseTtlMs: number;
maxAttempts: number;
runWaitMs?: number;
turnStream?: TurnStream;
runStreamEvents?: EventBus<RunStreamEvent>;
runActivity?: RunActivityStore;
signals?: RunSignalStore;
modelGateway: ModelGateway;
modelCredentials?: ModelCredentialStore;
userModelCredentials?: UserModelCredentialStore;
mcpServers?: McpServerStore;
mcpToolService?: McpToolService;
modelCredentialFetch?: typeof fetch;
modelRegistry?: ModelOverlayStore;
refreshModels?: () => Promise<void>;
customProviders?: CustomProviderStore;
refreshCustomProviders?: () => Promise<void>;
acl: AclStore;
admin?: AdminService;
skills: SkillStore;
skillPacks?: SkillPackStore;
skillFetcher?: SkillPackFetcher;
skillBundles?: SkillBundleStore;
advisoryLock?: AdvisoryLock;
auditLog: AuditLog;
config: ScopedConfigStore;
crons: CronStore;
webhooks: WebhookStore;
deliveries: DeliveryStore;
directory: DirectoryStore;
teams?: Pick<TeamStore, "isMember">;
emailAuthMembers?: DirectoryMember[];
projects?: ProjectStore;
deploy: DeployService;
deployAppsDomain?: string;
deploymentLayer?: DeploymentLayerRuntime;
files: FileArtifactStore;
approvals?: DurableMap<PendingApprovalRecord>;
sessionStateBus?: SessionStateBus;
ledgerEventBus?: LedgerEventBus;
contextRequests?: DurableMap<SurfaceContextRequest>;
environments?: EnvironmentStore;
processes?: ProcessRegistry;
monitors?: MonitorStore;
sandbox?: Sandbox;
reaperPoke?: () => void;
engaged?: EngagedRegistry;
surfaceCache?: SurfaceCache;
channelPolicy?: ChannelPolicyStore;
ambientJudge?: (systemPrompt: string, prompt: string, signal?: AbortSignal) => Promise<string | undefined>;
ambientCursors?: DurableMap<{ lastJudgedTs: string; lastJudgedAt?: number }>;
ambientJudgments?: AmbientJudgmentStore;
ackEmojiPicks?: AckEmojiPickStore;
judgeModelId?: () => string;
harnessId?: string;
modelProviders?: ModelProviderAvailability;
providerKeys?: ModelProviderAvailability;
runtimeFallback?: RuntimeChoice;
}
export interface ContextSummary {
scopeId: ScopeId;
kind: "personal" | "channel" | "group";
name: string | null;
isPrivate?: boolean;
sessionCount: number;
lastActivityAt: number | null;
project?: ProjectView;
}
interface FileListItem {
id: string;
ownerScopeId: ScopeId;
name: string;
mimetype: string;
sizeBytes: number;
direction: "in" | "out";
createdAt: number;
createdInScope?: ScopeId;
openable: boolean;
}
export interface FileListPage {
owned: FileListItem[];
shared: FileListItem[];
nextCursor?: string;
}
interface OpenedFile {
name: string;
mimetype: string;
sizeBytes: number;
stream: Readable;
}
export interface ScopeDeployment {
id: string;
name: string;
status: Deployment["status"];
permission: Permission;
currentVersion: number;
}
interface ScopeSkill {
id: string;
name: string;
description: string;
status: Skill["status"];
}
interface ScopeResources {
files: FileListItem[];
webhooks: Webhook[];
crons: Cron[];
deployments: ScopeDeployment[];
skills: ScopeSkill[];
manageable: boolean;
}
export function toFileItem(a: FileArtifact): FileListItem {
return {
id: a.id,
ownerScopeId: a.ownerScopeId,
name: a.name,
mimetype: a.mimetype,
sizeBytes: a.sizeBytes,
direction: a.direction,
createdAt: a.createdAt,
...(a.createdInScope ? { createdInScope: a.createdInScope } : {}),
openable: a.blobKey != null,
};
}
export class SoulUpdateDeniedError extends Error {
constructor() {
super("not authorized to update SOUL for this scope");
this.name = "SoulUpdateDeniedError";
}
}
export class SoulVersionConflictError extends Error {
constructor() {
super("Guidance changed; read it and retry the edit.");
this.name = "SoulVersionConflictError";
}
}
export const CONTEXT_REQUEST_EXPIRY_MS = 2 * 60_000;
export const STALE_LEASE_GRACE_MS = 30_000;
interface SessionPageQuery {
limit: number;
before?: { activity: number; id: string };
status?: SessionPageStatus;
surface?: string;
scopeId?: ScopeId;
titleQuery?: string;
}
export type SessionPageStatus = "active" | "archived" | "waiting";
interface SessionPageResult {
sessions: Session[];
pinned?: Session[];
next: { activity: number; id: string } | null;
hasArchived?: boolean;
}