@segmentstream/ontology 0.0.0-stage → 0.92.0

package/dist/errors.js

@@ -0,0 +1,109 @@
+import { Schema } from "effect";
+/** Safe batch failure locations: zero-based input indices and wire field names. */
+export const BatchErrorDetails = Schema.Struct({
+    indices: Schema.Array(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))),
+    fields: Schema.optionalKey(Schema.Array(Schema.String)),
+});
+const Count = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
+/**
+ * The platform limit that refused a file upload or attachment, with the numbers a caller needs to
+ * explain it in its own words. `usedBytes` counts current and retained historical file revisions,
+ * reserved uploads and live agent attachments.
+ */
+export const LimitErrorDetails = Schema.Union([
+    Schema.Struct({
+        kind: Schema.Literal("storage_quota"),
+        usedBytes: Count,
+        requestedBytes: Count,
+        quotaBytes: Count,
+    }),
+    Schema.Struct({
+        kind: Schema.Literal("pending_uploads"),
+        pending: Count,
+        max: Count,
+        /** The caller's open uploads, oldest first, which it can store with their actions or cancel. */
+        uploads: Schema.optionalKey(Schema.Array(Schema.Struct({ id: Schema.String, filename: Schema.String, expiresAt: Schema.String }))),
+    }),
+    Schema.Struct({ kind: Schema.Literal("member_attachments"), live: Count, max: Count }),
+]);
+/**
+ * An action refused the request for a business reason. The message is written for the caller and is
+ * returned to them.
+ */
+export class ActionRejected extends Schema.TaggedError()("ActionRejected", {
+    message: Schema.String,
+    cause: Schema.optionalKey(Schema.Unknown),
+    batch: Schema.optionalKey(BatchErrorDetails),
+    limit: Schema.optionalKey(LimitErrorDetails),
+}) {
+}
+/**
+ * The principal's roles do not grant a permission the request requires. The service answers 403
+ * with `<permission> is required.`; the message stays in the logs.
+ */
+export class PermissionDenied extends Schema.TaggedError()("PermissionDenied", {
+    message: Schema.String,
+    /** The permission that is missing, for example `lead:changeStatus`. */
+    permission: Schema.optionalKey(Schema.String),
+    /**
+     * Refused only because the running ontology and the database catalog differ, as while a
+     * deployment migrates. The caller retries the same request.
+     */
+    updating: Schema.optionalKey(Schema.Literal(true)),
+}) {
+}
+// @legacy ontology.workflow-cutover-artifacts
+/**
+ * A bounded deployment transition, which ontology SDKs 0.86.0 to 0.88.0 raised while their deploy
+ * guard paused workflow starts. Nothing raises it now; it is kept to read their recorded failures.
+ */
+export class DeploymentSwitching extends Schema.TaggedError()("DeploymentSwitching", {
+    message: Schema.String,
+    retryAfter: Schema.Number,
+    generation: Schema.optionalKey(Schema.String),
+}) {
+}
+/** This deployment cannot safely execute against the applied catalog. Retrying cannot repair it. */
+export class DeploymentInterrupted extends Schema.TaggedError()("DeploymentInterrupted", {
+    message: Schema.String,
+    servedHash: Schema.String,
+    appliedHash: Schema.optionalKey(Schema.String),
+    servedDeploymentId: Schema.optionalKey(Schema.String),
+    appliedDeploymentId: Schema.optionalKey(Schema.String),
+}) {
+}
+/** The write conflicts with existing data, for example a duplicate value of a unique property. */
+export class Conflict extends Schema.TaggedError()("Conflict", {
+    entity: Schema.String,
+    message: Schema.String,
+    property: Schema.optionalKey(Schema.String),
+    /**
+     * Seconds until the same request may succeed, set while another attempt holds the record, such
+     * as an upload whose storage call failed mid-flight.
+     */
+    retryAfter: Schema.optionalKey(Schema.Int),
+    batch: Schema.optionalKey(BatchErrorDetails),
+}) {
+}
+/** The record does not exist. */
+export class NotFound extends Schema.TaggedError()("NotFound", {
+    entity: Schema.String,
+    id: Schema.String,
+    message: Schema.String,
+    batch: Schema.optionalKey(BatchErrorDetails),
+}) {
+}
+/**
+ * A write would leave a record outside the scope of the permission that allowed it: the record
+ * matched the role's `where` before the change and does not after it. The service answers 403 with
+ * the entity and the permission; the scope's `where` and the values stay out of the response.
+ */
+export class ScopeViolated extends Schema.TaggedError()("ScopeViolated", {
+    entity: Schema.String,
+    id: Schema.optionalKey(Schema.String),
+    /** The scoped permission, for example `staff_member:update`. */
+    permission: Schema.String,
+    message: Schema.String,
+    batch: Schema.optionalKey(BatchErrorDetails),
+}) {
+}

package/dist/feedback-config.d.ts

@@ -0,0 +1,24 @@
+import type { Diagnostic } from "./diagnostics.js";
+import { type Role } from "./role.js";
+export interface FeedbackOptions {
+    readonly files?: boolean;
+    /** Preauthorize minimal technical failure reports during requested work; other feedback still asks. */
+    readonly automaticFailureReports?: boolean;
+    readonly builders?: ReadonlyArray<Role | string>;
+}
+export interface ResolvedFeedback {
+    readonly enabled: boolean;
+    readonly automaticFailureReports?: boolean;
+    readonly files: boolean;
+    readonly builders: ReadonlyArray<string>;
+}
+type Report = (code: Diagnostic["code"], path: string, message: string, severity?: Diagnostic["severity"]) => void;
+/** Validate the declaration without consulting storage or any other provider. */
+export declare function feedbackOptions(value: unknown, report: Report): FeedbackOptions | boolean;
+/** Add the fixed human role and builder grants, leaving the workspace's member role untouched. */
+export declare function feedbackRoles(options: FeedbackOptions | boolean, files: boolean, roles: ReadonlyArray<Role>, report: Report): {
+    readonly feedback: ResolvedFeedback;
+    readonly roles: ReadonlyArray<Role>;
+};
+export declare function checkFeedbackResponders(roles: ReadonlyArray<Role>, report: Report): void;
+export {};

package/dist/feedback-config.js

@@ -0,0 +1,126 @@
+import { nameToWire } from "./authoring-names.js";
+import { FEEDBACK_REPORTER_ROLE, MEMBER_ROLE } from "./names.js";
+import { isAllowed, normalizePermission } from "./permissions.js";
+import { isRole, role, roleEntries } from "./role.js";
+/** Validate the declaration without consulting storage or any other provider. */
+export function feedbackOptions(value, report) {
+    if (value === undefined) {
+        return {};
+    }
+    if (typeof value === "boolean") {
+        return value;
+    }
+    if (typeof value !== "object" ||
+        value === null ||
+        Array.isArray(value) ||
+        (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)) {
+        report("invalid-feedback", "feedback", "Use true, false, or { files, builders, automaticFailureReports }.");
+        return {};
+    }
+    const options = value;
+    for (const key of Object.keys(options)) {
+        if (key !== "files" && key !== "builders" && key !== "automaticFailureReports") {
+            report("invalid-feedback", `feedback.${key}`, `Unknown feedback option: ${key}.`);
+        }
+    }
+    if (options.files !== undefined && typeof options.files !== "boolean") {
+        report("invalid-feedback", "feedback.files", "files must be true or false.");
+    }
+    if (options.automaticFailureReports !== undefined &&
+        typeof options.automaticFailureReports !== "boolean") {
+        report("invalid-feedback", "feedback.automaticFailureReports", "automaticFailureReports must be true or false.");
+    }
+    if (options.builders !== undefined && !Array.isArray(options.builders)) {
+        report("invalid-feedback", "feedback.builders", "builders must be a list of declared roles or role names.");
+    }
+    return {
+        ...(typeof options.files === "boolean" ? { files: options.files } : {}),
+        ...(options.automaticFailureReports === true ? { automaticFailureReports: true } : {}),
+        ...(Array.isArray(options.builders) ? { builders: options.builders } : {}),
+    };
+}
+/** Add the fixed human role and builder grants, leaving the workspace's member role untouched. */
+export function feedbackRoles(options, files, roles, report) {
+    if (options === false) {
+        return { feedback: { enabled: false, files: false, builders: [] }, roles };
+    }
+    const configured = typeof options === "object" ? options.builders : undefined;
+    const builders = new Set();
+    if (configured === undefined) {
+        for (const candidate of roles) {
+            if (candidate.name !== MEMBER_ROLE &&
+                Array.isArray(candidate.permissions) &&
+                candidate.permissions.some((permission) => ["user:grant_roles", "user:*"].includes(normalizePermission(permission)))) {
+                builders.add(candidate.name);
+            }
+        }
+    }
+    else {
+        configured.forEach((candidate, index) => {
+            const name = typeof candidate === "string"
+                ? nameToWire(candidate)
+                : isRole(candidate)
+                    ? nameToWire(candidate.name)
+                    : undefined;
+            if (name === undefined ||
+                name === MEMBER_ROLE ||
+                name === FEEDBACK_REPORTER_ROLE ||
+                !roles.some((declared) => declared.name === name)) {
+                report("invalid-feedback", `feedback.builders[${index}]`, "A builder must name a declared role other than member or feedback_reporter.");
+            }
+            else {
+                builders.add(name);
+            }
+        });
+    }
+    const resolved = roles.map((candidate) => !builders.has(candidate.name)
+        ? candidate
+        : role(candidate.name, {
+            description: candidate.description,
+            permissions: [
+                ...roleEntries(Array.isArray(candidate.permissions) ? candidate.permissions : [], candidate.scopes ?? []),
+                "app_feedback:read",
+                "app_feedback:respond",
+                ...(files ? ["app_feedback_file:read"] : []),
+            ],
+        }));
+    const own = { reporter: { $me: [] } };
+    resolved.push(role(FEEDBACK_REPORTER_ROLE, {
+        description: "Implicit feedback authority of authenticated human members; never assigned.",
+        permissions: [
+            "app_feedback:submit",
+            { permission: "app_feedback:read", where: own },
+            { permission: "app_feedback:acknowledge", where: own },
+            ...(files
+                ? [
+                    { permission: "app_feedback_file:attach", where: { feedback: own } },
+                    { permission: "app_feedback_file:read", where: { feedback: own } },
+                ]
+                : []),
+        ],
+    }));
+    return {
+        feedback: {
+            enabled: true,
+            files,
+            builders: [...builders],
+            ...(typeof options === "object" && options.automaticFailureReports === true
+                ? { automaticFailureReports: true }
+                : {}),
+        },
+        roles: resolved,
+    };
+}
+export function checkFeedbackResponders(roles, report) {
+    const member = roles.find((candidate) => candidate.name === MEMBER_ROLE);
+    if (!roles.some((candidate) => {
+        const permissions = [
+            ...(Array.isArray(member?.permissions) ? member.permissions : []),
+            ...(Array.isArray(candidate.permissions) ? candidate.permissions : []),
+        ];
+        return (isAllowed("app_feedback:respond", { permissions }) &&
+            isAllowed("app_feedback:read", { permissions }));
+    })) {
+        report("feedback-unanswerable", "feedback.builders", "No effective role can read and answer feedback. Configure feedback: { builders: [...] }.", "warning");
+    }
+}

package/dist/files.d.ts

@@ -0,0 +1,39 @@
+import { Context, type Effect, type Scope, type Stream } from "effect";
+import type { BlobUpload, BlobValue } from "./blob.js";
+import type { ActionError } from "./errors.js";
+/** A file property an authored action may populate during preparation. */
+export interface FileTarget {
+    readonly entity: string;
+    readonly property: string;
+}
+export interface StageFile<E, R> {
+    readonly target: FileTarget;
+    /** Stable source identity within this action or workflow step's idempotency key. */
+    readonly key: string;
+    readonly recordId?: string;
+    readonly createIntent?: string;
+    readonly filename: string;
+    readonly contentType: string;
+    readonly size: number;
+    /** Required in a workflow step; preparation is bound to its own action. */
+    readonly action?: string;
+    /** Opened only when the upload still needs bytes. */
+    readonly open: () => Effect.Effect<Stream.Stream<Uint8Array, E, R>, E, R>;
+}
+export interface OpenFile {
+    readonly entity: string;
+    readonly id: string;
+    readonly property: string;
+    readonly revisionId?: string;
+}
+declare const Files_base: Context.ServiceClass<Files, "@segmentstream/ontology/Files", {
+    readonly stage: <E, R>(input: StageFile<E, R>) => Effect.Effect<BlobUpload, E | ActionError, R>;
+    readonly open: (input: OpenFile) => Effect.Effect<{
+        readonly file: BlobValue;
+        readonly body: Stream.Stream<Uint8Array, ActionError>;
+    }, ActionError, Scope.Scope>;
+}>;
+/** File I/O outside transactions, bound to the current action or workflow principal. */
+export declare class Files extends Files_base {
+}
+export {};

package/dist/files.js

@@ -0,0 +1,4 @@
+import { Context } from "effect";
+/** File I/O outside transactions, bound to the current action or workflow principal. */
+export class Files extends Context.Service()("@segmentstream/ontology/Files") {
+}

package/dist/groups.d.ts

@@ -0,0 +1,95 @@
+/** Channel-independent group policy. All names and aliases are supplied by the workspace. */
+export interface SmartPolicyInput {
+    readonly model?: string;
+    readonly instructions?: string | {
+        readonly append?: string;
+        readonly replace?: string;
+        readonly file?: string;
+    };
+    readonly criteria?: {
+        readonly observe?: string;
+        readonly reply?: string;
+    };
+    readonly context?: {
+        readonly messages?: number;
+        readonly includeAgentDescription?: boolean;
+        /**
+         * @legacy agent.config-retired-keys
+         * @deprecated Accepted so that configurations written for agent 0.9 and 0.10 still deploy;
+         * it has no effect. The router no longer receives the agent's instructions.
+         */
+        readonly includeAgentInstructions?: boolean | {
+            readonly maxChars: number;
+        };
+        readonly includeChatGuidance?: boolean;
+        readonly includeParticipants?: boolean;
+    };
+    readonly engagement?: {
+        readonly policy?: string;
+        readonly agentAliases?: ReadonlyArray<string>;
+        readonly idleMinutes?: number;
+        readonly humanExchangeMinutes?: number;
+        readonly humanQuestionMinutes?: number;
+        readonly inferredMaxMinutes?: number;
+        readonly burst?: {
+            readonly quietSeconds?: number;
+            readonly maxSeconds?: number;
+            readonly gapSeconds?: number;
+        };
+        readonly followUpMinutes?: number;
+        readonly conversationMinutes?: number;
+        readonly openQuestionMinutes?: number | "unlimited";
+        readonly addresseeGate?: boolean;
+    };
+    readonly thresholds?: {
+        readonly continuation?: number;
+        readonly inferredContinuation?: number;
+        readonly contested?: number;
+        readonly ambient?: number;
+        readonly humanExchange?: number;
+        readonly engaged?: number;
+        readonly neutral?: number;
+        readonly humanThread?: number;
+        /**
+         * Conversation policy: the agent answers when the decision model gives at least this
+         * probability that it is addressed and that a reply is needed (0.5..1, default 0.5).
+         */
+        readonly reply?: number;
+        /**
+         * Conversation policy: a message below `reply` but at or above `defer` still reaches the
+         * agent, which answers or calls `no_reply`; so does a message the decision model could not
+         * classify. Defaults to `reply`, which leaves no such band.
+         */
+        readonly defer?: number;
+    };
+    readonly timeoutSeconds?: number;
+}
+export type Participants = Readonly<Record<string, {
+    readonly aliases: ReadonlyArray<string>;
+}>>;
+export interface ChatOverrideInput {
+    readonly mode?: string;
+    readonly smart?: Pick<SmartPolicyInput, "instructions" | "criteria" | "engagement" | "thresholds"> & {
+        readonly context?: Pick<NonNullable<SmartPolicyInput["context"]>, "messages" | "includeChatGuidance">;
+    };
+    readonly participants?: Participants;
+}
+export interface GroupPolicyInput {
+    readonly mode?: string;
+    readonly smart?: SmartPolicyInput;
+    /** Aliases of the people in every group chat; a chat's own `participants` add to them. */
+    readonly participants?: Participants;
+    readonly chats?: Readonly<Record<string, ChatOverrideInput>>;
+    readonly observability?: {
+        readonly storeRouterPayload?: boolean;
+        readonly shadow?: SmartPolicyInput;
+    };
+}
+export interface GroupPolicyIssue {
+    readonly message: string;
+    readonly path: ReadonlyArray<string>;
+}
+/** Strict validation of the `groups` section that `agent/segmentstream.json` authors. */
+export declare function groupPolicyIssues(value: unknown): ReadonlyArray<GroupPolicyIssue>;
+/** Expand authored files before bundling. The caller owns the workspace-relative filesystem boundary. */
+export declare function expandGroupFiles(input: GroupPolicyInput, read: (path: string) => string): GroupPolicyInput;