@ever-works/contracts 1.0.0

package/dist/feed.types-BWk3CHqj.d.ts

@@ -0,0 +1,355 @@
+/**
+ * Merge policy — the configurable enforcement matrix for agent-driven merges
+ * (Wave 3, founder decision D4).
+ *
+ * The platform does NOT hardcode whether an agent may merge its own pull
+ * request. Whether it may is a POLICY, resolvable at four scopes
+ * (tenant → organization → Work → Agent) and layered over a conservative
+ * platform DEFAULT. Operators keep the safe posture by doing nothing and can
+ * opt into "agents merge when green" — or anything in between — per scope.
+ *
+ * This package holds the zero-dependency storage/wire shapes only. The
+ * resolution algorithm, the deep merge and the single decision point
+ * (`canAgentMerge`) live in `@ever-works/agent` (`policy/`), and enforcement
+ * lives at the git facade + the Task finalize path.
+ */
+/** Merge strategy a provider can be asked to use when landing a pull request. */
+type MergeMethod = 'merge' | 'squash' | 'rebase';
+/**
+ * Canonical list of merge methods. Kept as a const so validators (DTO
+ * `@IsIn`, import sanitizers) share one source of truth with the type.
+ */
+declare const MERGE_METHODS: readonly MergeMethod[];
+/**
+ * The fully-resolved policy. Every field is REQUIRED here — a resolved policy
+ * is always complete, because unset fields fall through to the next scope and
+ * ultimately to {@link PLATFORM_DEFAULT_MERGE_POLICY}.
+ */
+interface MergePolicy {
+    /**
+     * May an agent land a pull request at all? `false` does not stop the agent
+     * from OPENING one (that is `AgentPermissions.canOpenPullRequests`) — it
+     * stops the merge itself.
+     */
+    allowAgentMerge: boolean;
+    /** Require the run's quality gate to be green before an agent may merge. */
+    requireGreenGate: boolean;
+    /** Require a recorded human approval before an agent may merge. */
+    requireHumanApproval: boolean;
+    /** Merge strategies an agent may use. An empty list refuses every merge. */
+    allowedMergeMethods: MergeMethod[];
+    /**
+     * Branch names an agent may never merge INTO, matched case-insensitively
+     * against the pull request's base branch (a leading `refs/heads/` is
+     * stripped before comparison).
+     */
+    protectedBranches: string[];
+}
+/**
+ * The scopes a policy can be stored at, from least to most specific. The
+ * most specific scope that declares a field wins for THAT field
+ * (see {@link MERGE_POLICY_SCOPE_PRECEDENCE}).
+ */
+type MergePolicyScope = 'tenant' | 'organization' | 'work' | 'agent';
+/**
+ * Documented precedence, least specific first:
+ *
+ *   platform default  <  tenant  <  organization  <  Work  <  Agent
+ *
+ * Resolution is FIELD-BY-FIELD (a deep merge, not a whole-object override):
+ * a Work that sets only `allowAgentMerge` inherits the other four fields from
+ * its organization / tenant / the platform default. `null` or an omitted key
+ * at any scope means "inherit", never "false".
+ */
+declare const MERGE_POLICY_SCOPE_PRECEDENCE: readonly MergePolicyScope[];
+/**
+ * What a scope actually stores: a PARTIAL policy. Absent/`null` fields
+ * inherit from the next-least-specific scope. This is the shape of the
+ * additive `mergePolicy` `simple-json` column on `tenants`, `organizations`,
+ * `works` and `agents`.
+ */
+type MergePolicyOverride = Partial<MergePolicy>;
+/**
+ * Which scope a resolved policy (or one of its fields) came from. `'default'`
+ * means no scope in the chain declared it and the platform default applies.
+ */
+type MergePolicySource = MergePolicyScope | 'default';
+/**
+ * The platform DEFAULT — deliberately conservative, and deliberately NOT a
+ * hardcode: every field is overridable at any of the four scopes. An operator
+ * who wants agents to land their own green work sets
+ * `{ allowAgentMerge: true, requireHumanApproval: false }` at the scope of
+ * their choosing.
+ */
+declare const PLATFORM_DEFAULT_MERGE_POLICY: MergePolicy;
+/** Every field name of {@link MergePolicy}; the deep-merge iterates this. */
+declare const MERGE_POLICY_FIELDS: readonly (keyof MergePolicy)[];
+/** One link of the resolution chain, reported so a preview can explain itself. */
+interface MergePolicyChainEntry {
+    /** The scope this link represents (`'default'` is always the first link). */
+    scope: MergePolicySource;
+    /** Row id of the scope entity; `null` for the platform default. */
+    id: string | null;
+    /**
+     * Fields this link CONTRIBUTED to the final policy — i.e. it declared them
+     * and no more specific link overrode them. An empty array means the link
+     * exists in the ancestry but was fully shadowed (or declared nothing).
+     */
+    fields: (keyof MergePolicy)[];
+}
+/** Result of one policy resolution. */
+interface ResolvedMergePolicy {
+    /** The complete, effective policy. */
+    policy: MergePolicy;
+    /**
+     * The MOST SPECIFIC scope that contributed at least one field, or
+     * `'default'` when nothing in the chain declared anything.
+     */
+    source: MergePolicySource;
+    /** Least → most specific, starting at the platform default. */
+    chain: MergePolicyChainEntry[];
+}
+/**
+ * Stable refusal codes from the single decision point. Kept machine-readable
+ * so callers (facade, worker, UI) can branch without string-matching prose.
+ */
+type MergeRefusalCode = 'agent-merge-disabled' | 'protected-branch' | 'target-branch-unknown' | 'merge-method-not-allowed' | 'gate-not-green' | 'human-approval-required'
+/** No recorded approval names this pull request at all. */
+ | 'approval-missing'
+/** An approval exists for this pull request, but for an EARLIER head commit. */
+ | 'approval-stale'
+/** A matching approval exists but is older than `MERGE_APPROVAL_MAX_AGE_MS`. */
+ | 'approval-expired'
+/** The recorded decision was not made by a human (guardrail / no decider). */
+ | 'approval-not-human'
+/** The approver is not entitled to approve for this Task's scope. */
+ | 'approver-not-entitled'
+/** The pull request is draft/closed/merged at merge time. */
+ | 'pull-request-not-open'
+/** Provider CI is not green at merge time (it may have been at approval time). */
+ | 'pull-request-not-green'
+/** The live head commit could not be read, so nothing can be pinned to it. */
+ | 'head-sha-unknown';
+/** Outcome of the single decision point (`canAgentMerge`). */
+interface MergeDecision {
+    allowed: boolean;
+    /** Human-readable explanation; present only when `allowed === false`. */
+    reason?: string;
+    /** Machine-readable counterpart of `reason`. */
+    code?: MergeRefusalCode;
+    /** The policy the decision was made against, and where it came from. */
+    source?: MergePolicySource;
+}
+
+/**
+ * Connection credential transport (AW-15) — the organization setting and the
+ * pure verdict every create, update and connection attempt shares.
+ *
+ * ## What already worked, and what is new
+ *
+ * An MCP connection whose auth headers hold LITERAL values has always been
+ * able to use a plain `http://` endpoint. That keeps working: such a
+ * connection is allowed and flagged `insecure_transport` (a warning) so the
+ * owner sees the credential travels unencrypted.
+ *
+ * Resolving `{{cred.key}}` references inside headers is new, so nothing relies
+ * on sending a resolved secret over plain http. A reference aimed at a
+ * plain-http endpoint is refused (`https_required`) and the secret is never
+ * looked up.
+ *
+ * An organization can opt into refusing literal credentials over plain http
+ * too, with the setting below. It is OFF unless the organization turns it on.
+ */
+/** Stored on `organizations.connection_policy`. `null` / `{}` = every default. */
+interface OrganizationConnectionPolicy {
+    /**
+     * "Require https for connection credentials". When `true`, a connection
+     * whose auth headers carry ANY value (literal or reference) must use an
+     * `https:` endpoint. Default `false`: literal credentials over plain http
+     * keep working, with a warning.
+     */
+    requireHttpsForCredentials?: boolean;
+}
+/** The setting's key inside `OrganizationConnectionPolicy`. */
+declare const REQUIRE_HTTPS_FOR_CREDENTIALS_SETTING: "requireHttpsForCredentials";
+/** The setting's human name, used verbatim in every refusal it causes. */
+declare const REQUIRE_HTTPS_FOR_CREDENTIALS_SETTING_LABEL = "Require https for connection credentials";
+/**
+ * Shape guard for the stored / submitted policy. Unknown keys are dropped and
+ * only a real boolean is kept, so a junk value can never switch enforcement on
+ * or off by accident. An object with nothing left is `null` ("all defaults").
+ */
+declare function sanitizeOrganizationConnectionPolicy(raw: unknown): OrganizationConnectionPolicy | null;
+/** Does this stored policy refuse literal credentials over plain http? Default: no. */
+declare function organizationRequiresHttpsForCredentials(policy: unknown): boolean;
+/**
+ * The verdict for one endpoint + header map.
+ *
+ *   secure          no credential leaves in cleartext (https, stdio, or no headers)
+ *   insecure        literal credentials over plain http — allowed, with a warning
+ *   refused         nothing may be sent; `reason` says why
+ */
+type CredentialTransportVerdict = {
+    verdict: 'secure';
+} | {
+    verdict: 'insecure';
+} | {
+    verdict: 'refused';
+    reason: CredentialTransportRefusalReason;
+};
+/**
+ *   credential_references  a `{{cred.key}}` reference aimed at plain http
+ *   organization_policy    literal credentials over plain http while the
+ *                          organization requires https
+ */
+type CredentialTransportRefusalReason = 'credential_references' | 'organization_policy';
+interface CredentialTransportInput {
+    url: string | null | undefined;
+    transport?: string | null;
+    headers: Readonly<Record<string, string>> | null | undefined;
+    /** The organization setting. Omitted / `false` = literal credentials over http stay allowed. */
+    requireHttpsForCredentials?: boolean;
+}
+/**
+ * Decide how one connection may send its headers.
+ *
+ * `stdio` rows are exempt — they never dial a network address. A header map
+ * with no non-empty value carries no credential, so plain http without
+ * headers is `secure` in every case (it sends nothing to protect).
+ */
+declare function assessCredentialTransport(input: CredentialTransportInput): CredentialTransportVerdict;
+
+/**
+ * Live Feed — wire types for the narrated view of the activity log.
+ *
+ * The Live Feed is a reading surface over the `activity_log` rows Ever Works
+ * already writes. It owns no store of its own: every entry below is one
+ * existing activity record, projected into a line a person can read without
+ * decoding an action token.
+ *
+ * The API returns STRUCTURE, never English. A narration is a message key plus
+ * sanitized parameters, and a destination is a typed pointer, so the web
+ * renders both through its own translations and route constants and any
+ * other client (CLI, MCP) can do the same.
+ */
+/** The five buckets every entry classifies into. Derived, never stored. */
+type FeedKind = 'work' | 'decision' | 'delivery' | 'problem' | 'system';
+/** Display order of the kind chips (keyboard `1`-`5` follows this order). */
+declare const FEED_KINDS: readonly FeedKind[];
+/**
+ * Who did the thing: an agent, the signed-in user, an external source
+ * (a connector, a repository, a deployed site), or the platform itself.
+ */
+type FeedActorKind = 'agent' | 'user' | 'external' | 'system';
+declare const FEED_ACTOR_KINDS: readonly FeedActorKind[];
+/** Default page size. */
+declare const FEED_PAGE_SIZE_DEFAULT = 30;
+/** A page never holds more than this many entries. */
+declare const FEED_PAGE_SIZE_MAX = 50;
+/** At most this many agents can be watched at once. */
+declare const FEED_MAX_AGENT_FILTER = 20;
+/** How far back the feed reads. Older records stay on the Activity log. */
+declare const FEED_HISTORY_DAYS = 90;
+/** Automatic paging stops after this many pages in one visit. */
+declare const FEED_MAX_AUTO_PAGES = 20;
+/** Every interpolated narration value is truncated to this many characters. */
+declare const FEED_NARRATION_PARAM_MAX_CHARS = 120;
+/** Default and maximum look-back window of the actor roster, in hours. */
+declare const FEED_ACTORS_WINDOW_HOURS_DEFAULT = 168;
+declare const FEED_ACTORS_WINDOW_HOURS_MAX = 720;
+interface FeedActorDto {
+    kind: FeedActorKind;
+    /** Set when `kind === 'agent'`. */
+    agentId?: string | null;
+    /**
+     * Display name. For an agent, the name captured when the record was
+     * written, else the agent's current name. `null` when no name is known,
+     * in which case the renderer uses its own label for the kind.
+     */
+    label: string | null;
+    /** An agent's avatar mode, when it still exists. */
+    avatarMode?: string | null;
+}
+interface FeedNarrationDto {
+    /** A leaf key under the renderer's narration namespace, or `fallback`. */
+    key: string;
+    /** Sanitized values. Only fields allowed for the action type ever appear. */
+    params: Record<string, string | number>;
+}
+/** What an entry can point at. */
+type FeedTargetType = 'run' | 'task' | 'mission' | 'idea' | 'agent' | 'work' | 'inbox' | 'skill';
+declare const FEED_TARGET_TYPES: readonly FeedTargetType[];
+/**
+ * The most specific thing an entry is about. `null` on the entry when there
+ * is nothing to open (for example the agent was deleted), in which case the
+ * entry renders as plain text rather than a dead link.
+ */
+interface FeedTargetDto {
+    type: FeedTargetType;
+    id: string;
+}
+interface FeedEntryDto {
+    /** The activity record id. */
+    id: string;
+    /** ISO timestamp of when it happened. */
+    createdAt: string;
+    kind: FeedKind;
+    /** The record's own status (`pending`, `in_progress`, `completed`, `failed`, `cancelled`). */
+    status: string;
+    /** The record's action type, for clients that want to group or count. */
+    actionType: string;
+    actor: FeedActorDto;
+    narration: FeedNarrationDto;
+    target: FeedTargetDto | null;
+    workId?: string | null;
+}
+interface FeedPageDto {
+    /** Newest first. */
+    items: FeedEntryDto[];
+    /** Opaque cursor for the next older page, or `null` at the end. */
+    nextCursor: string | null;
+    hasMore: boolean;
+    /** Oldest point the feed reads back to (ISO). Paging stops here. */
+    historyFloor: string;
+    /** Populated once per-user seen state is available. */
+    unseenCount?: number;
+    lastSeenAt?: string | null;
+}
+interface FeedActorSummaryDto {
+    agentId: string;
+    label: string;
+    /** The agent's current status (`active`, `running`, `paused`, ...). */
+    status: string;
+    avatarMode?: string | null;
+    /** Entries attributed to the agent inside the requested window. */
+    count: number;
+    /** ISO timestamp of the agent's newest entry in the window, if any. */
+    lastActivityAt: string | null;
+}
+interface FeedActorsDto {
+    actors: FeedActorSummaryDto[];
+    windowHours: number;
+}
+/** Computed while-you-were-away payload. Never stored. */
+interface FeedAwaySummaryDto {
+    awayForMs: number;
+    windowStart: string;
+    windowEnd: string;
+    truncatedToWindow: boolean;
+    truncatedToScanCap: boolean;
+    total: number;
+    byKind: Record<FeedKind, number>;
+    topActors: FeedActorSummaryDto[];
+    otherActorCount: number;
+    decisionsWaiting: number;
+    failures: number;
+    narrative?: {
+        text: string;
+        model: string;
+        tokens: number;
+    } | null;
+}
+/** Stable error codes the feed endpoints answer with. */
+type FeedErrorCode = 'invalid-cursor' | 'too-many-agents';
+
+export { MERGE_POLICY_SCOPE_PRECEDENCE as A, type MergeDecision as B, type CredentialTransportInput as C, type MergeMethod as D, type MergePolicy as E, type FeedNarrationDto as F, type MergePolicyChainEntry as G, type MergePolicyScope as H, type MergePolicySource as I, type MergeRefusalCode as J, REQUIRE_HTTPS_FOR_CREDENTIALS_SETTING_LABEL as K, type ResolvedMergePolicy as L, type MergePolicyOverride as M, assessCredentialTransport as N, type OrganizationConnectionPolicy as O, PLATFORM_DEFAULT_MERGE_POLICY as P, organizationRequiresHttpsForCredentials as Q, REQUIRE_HTTPS_FOR_CREDENTIALS_SETTING as R, sanitizeOrganizationConnectionPolicy as S, type FeedEntryDto as a, type CredentialTransportRefusalReason as b, type CredentialTransportVerdict as c, FEED_ACTORS_WINDOW_HOURS_DEFAULT as d, FEED_ACTORS_WINDOW_HOURS_MAX as e, FEED_ACTOR_KINDS as f, FEED_HISTORY_DAYS as g, FEED_KINDS as h, FEED_MAX_AGENT_FILTER as i, FEED_MAX_AUTO_PAGES as j, FEED_NARRATION_PARAM_MAX_CHARS as k, FEED_PAGE_SIZE_DEFAULT as l, FEED_PAGE_SIZE_MAX as m, FEED_TARGET_TYPES as n, type FeedActorDto as o, type FeedActorKind as p, type FeedActorSummaryDto as q, type FeedActorsDto as r, type FeedAwaySummaryDto as s, type FeedErrorCode as t, type FeedKind as u, type FeedPageDto as v, type FeedTargetDto as w, type FeedTargetType as x, MERGE_METHODS as y, MERGE_POLICY_FIELDS as z };

package/dist/form/index.cjs

@@ -0,0 +1,2 @@
+'use strict';
+

package/dist/form/index.d.cts

@@ -0,0 +1,104 @@
+/**
+ * Form field types supported by the plugin system
+ */
+type FormFieldType = 'text' | 'textarea' | 'number' | 'boolean' | 'select' | 'multiselect' | 'date' | 'datetime' | 'url' | 'email' | 'password' | 'file' | 'image' | 'color' | 'json' | 'markdown' | 'code' | 'rich-text' | 'tags' | 'rating' | 'range' | 'hidden';
+/**
+ * Option for select/multiselect fields
+ */
+interface FormFieldOption {
+    readonly label: string;
+    readonly value: string | number | boolean;
+    readonly description?: string;
+    readonly disabled?: boolean;
+}
+/**
+ * Validation rule for a form field
+ */
+interface FormFieldValidation {
+    /** Required field */
+    readonly required?: boolean;
+    /** Minimum value (number) or length (string) */
+    readonly min?: number;
+    /** Maximum value (number) or length (string) */
+    readonly max?: number;
+    /** Regular expression pattern for validation */
+    readonly pattern?: string;
+    /** Custom error message */
+    readonly message?: string;
+}
+/**
+ * Conditional visibility/requirement based on other field values
+ */
+interface FormFieldCondition {
+    /** Field name to check */
+    readonly field: string;
+    /** Operator for comparison */
+    readonly operator: 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'not_contains';
+    /** Value to compare against */
+    readonly value: unknown;
+}
+/**
+ * Definition for a form field
+ */
+interface FormFieldDefinition {
+    /** Unique identifier for the field */
+    readonly name: string;
+    /** Field type */
+    readonly type: FormFieldType;
+    /** Display label */
+    readonly label: string;
+    /** Help text or description */
+    readonly description?: string;
+    /** Placeholder text */
+    readonly placeholder?: string;
+    /** Default value */
+    readonly defaultValue?: unknown;
+    /** Options for select/multiselect fields */
+    readonly options?: readonly FormFieldOption[];
+    /** Validation rules */
+    readonly validation?: FormFieldValidation;
+    /** Conditional visibility */
+    readonly showIf?: FormFieldCondition | readonly FormFieldCondition[];
+    /** Conditional requirement */
+    readonly requiredIf?: FormFieldCondition | readonly FormFieldCondition[];
+    /** Whether the field is disabled */
+    readonly disabled?: boolean;
+    /** Whether the field is read-only */
+    readonly readOnly?: boolean;
+    /** Group/section for organizing fields */
+    readonly group?: string;
+    /** Display order within group */
+    readonly order?: number;
+    /** Additional field-specific configuration */
+    readonly config?: Record<string, unknown>;
+}
+/**
+ * Group of related form fields
+ */
+interface FormFieldGroup {
+    /** Unique identifier for the group */
+    readonly name: string;
+    /** Display title */
+    readonly title: string;
+    /** Group description */
+    readonly description?: string;
+    /** Display order */
+    readonly order?: number;
+    /** Whether the group is collapsible */
+    readonly collapsible?: boolean;
+    /** Whether the group starts collapsed */
+    readonly collapsed?: boolean;
+}
+/**
+ * Complete form schema with fields and groups
+ */
+interface FormSchema {
+    /** Form fields */
+    readonly fields: readonly FormFieldDefinition[];
+    /** Field groups */
+    readonly groups?: readonly FormFieldGroup[];
+    /** Form-level validation */
+    readonly validation?: Record<string, unknown>;
+}
+
+export type { FormFieldCondition, FormFieldDefinition, FormFieldGroup, FormFieldOption, FormFieldType, FormFieldValidation, FormSchema };

package/dist/form/index.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Form field types supported by the plugin system
+ */
+type FormFieldType = 'text' | 'textarea' | 'number' | 'boolean' | 'select' | 'multiselect' | 'date' | 'datetime' | 'url' | 'email' | 'password' | 'file' | 'image' | 'color' | 'json' | 'markdown' | 'code' | 'rich-text' | 'tags' | 'rating' | 'range' | 'hidden';
+/**
+ * Option for select/multiselect fields
+ */
+interface FormFieldOption {
+    readonly label: string;
+    readonly value: string | number | boolean;
+    readonly description?: string;
+    readonly disabled?: boolean;
+}
+/**
+ * Validation rule for a form field
+ */
+interface FormFieldValidation {
+    /** Required field */
+    readonly required?: boolean;
+    /** Minimum value (number) or length (string) */
+    readonly min?: number;
+    /** Maximum value (number) or length (string) */
+    readonly max?: number;
+    /** Regular expression pattern for validation */
+    readonly pattern?: string;
+    /** Custom error message */
+    readonly message?: string;
+}
+/**
+ * Conditional visibility/requirement based on other field values
+ */
+interface FormFieldCondition {
+    /** Field name to check */
+    readonly field: string;
+    /** Operator for comparison */
+    readonly operator: 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'not_contains';
+    /** Value to compare against */
+    readonly value: unknown;
+}
+/**
+ * Definition for a form field
+ */
+interface FormFieldDefinition {
+    /** Unique identifier for the field */
+    readonly name: string;
+    /** Field type */
+    readonly type: FormFieldType;
+    /** Display label */
+    readonly label: string;
+    /** Help text or description */
+    readonly description?: string;
+    /** Placeholder text */
+    readonly placeholder?: string;
+    /** Default value */
+    readonly defaultValue?: unknown;
+    /** Options for select/multiselect fields */
+    readonly options?: readonly FormFieldOption[];
+    /** Validation rules */
+    readonly validation?: FormFieldValidation;
+    /** Conditional visibility */
+    readonly showIf?: FormFieldCondition | readonly FormFieldCondition[];
+    /** Conditional requirement */
+    readonly requiredIf?: FormFieldCondition | readonly FormFieldCondition[];
+    /** Whether the field is disabled */
+    readonly disabled?: boolean;
+    /** Whether the field is read-only */
+    readonly readOnly?: boolean;
+    /** Group/section for organizing fields */
+    readonly group?: string;
+    /** Display order within group */
+    readonly order?: number;
+    /** Additional field-specific configuration */
+    readonly config?: Record<string, unknown>;
+}
+/**
+ * Group of related form fields
+ */
+interface FormFieldGroup {
+    /** Unique identifier for the group */
+    readonly name: string;
+    /** Display title */
+    readonly title: string;
+    /** Group description */
+    readonly description?: string;
+    /** Display order */
+    readonly order?: number;
+    /** Whether the group is collapsible */
+    readonly collapsible?: boolean;
+    /** Whether the group starts collapsed */
+    readonly collapsed?: boolean;
+}
+/**
+ * Complete form schema with fields and groups
+ */
+interface FormSchema {
+    /** Form fields */
+    readonly fields: readonly FormFieldDefinition[];
+    /** Field groups */
+    readonly groups?: readonly FormFieldGroup[];
+    /** Form-level validation */
+    readonly validation?: Record<string, unknown>;
+}
+
+export type { FormFieldCondition, FormFieldDefinition, FormFieldGroup, FormFieldOption, FormFieldType, FormFieldValidation, FormSchema };

package/dist/form/index.js

@@ -0,0 +1 @@
+