apps 0.0.1-beta.46 → 0.0.1-beta.48

package/types/apps/src/contracts/app.d.ts

@@ -57,6 +57,8 @@ export interface BoundContext<Slots extends AccountSlots> {
 /** The host evaluates this factory fresh with the configured app's selected accounts. */
 export interface App<Slots extends AccountSlots, Def extends AppDefinition<never>> {
     readonly accounts: Slots;
+    /** Declared beside the accounts, so a host lists them without evaluating the app. */
+    readonly events?: Readonly<Record<string, import("./events.js").AppEvent>>;
     readonly evaluate: (context: BoundContext<Slots>) => Effect.Effect<Def, unknown>;
 }
 declare const NotImplemented_base: Schema.Class<NotImplemented, Schema.TaggedStruct<"NotImplemented", {

package/types/apps/src/contracts/context.d.ts

@@ -2,10 +2,17 @@
 import type { WorkflowControls } from "./workflows.js";
 import type { AccountSlots, BoundContext } from "./app.js";
 import type { Sql, SqlReader } from "./sql.js";
+import type { AnyEventDeclaration, EventEmitter } from "../implementation/events.js";
 /** Requirements are pure values; selected accounts and SQL access belong to invocations. */
 export interface AppRequirements {
     readonly accounts: AccountSlots;
+    /** Events this app emits, by name, such as `issue.opened`. */
+    readonly events?: Readonly<Record<string, AnyEventDeclaration>>;
 }
+/** The emitter for an app's declared events. */
+type EventsContext<Requirements extends AppRequirements> = {
+    readonly events: EventEmitter<NonNullable<Requirements["events"]>>;
+};
 /**
  * Every handler has `ctx.sql`. The app's database exists once the build has SQL files in
  * `migrations/`; before that, any statement fails and says so.
@@ -20,7 +27,7 @@ export type QueryContext<Requirements extends AppRequirements = AppRequirements>
 /** Interactive mutation context; outside calls happen between SQL transactions, never inside one. */
 export type MutationContext<Requirements extends AppRequirements = AppRequirements> = Omit<AppContext<Requirements>, "workflows"> & {
     readonly workflows: WorkflowControls;
-} & StorageContext<true>;
+} & StorageContext<true> & EventsContext<Requirements>;
 /** Background webhook context has account and storage access without interactive input. */
 export type WebhookContext<Requirements extends AppRequirements = AppRequirements> = Omit<MutationContext<Requirements>, "elicit">;
 export {};

package/types/apps/src/contracts/events.d.ts

@@ -0,0 +1,93 @@
+/**
+ * App events. An app declares the events it emits beside its account requirements, so a host
+ * reads them without evaluating the app. Handlers emit occurrences; the host keeps them only
+ * when the invocation that emitted them succeeds, then delivers them to its subscribers.
+ */
+import { Schema } from "effect";
+/** Dotted lower-case words, such as `issue.opened`. Hosts prefix them with the app's slug. */
+export declare const EventName: Schema.String;
+export type EventName = typeof EventName.Type;
+/** A filter value: subscribers match an occurrence by equal scalars. */
+export declare const EventFilterValue: Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>;
+export type EventFilterValue = typeof EventFilterValue.Type;
+/** Size and count limits for events; bytes are UTF-8 bytes of the JSON text. */
+export declare const EventLimits: Schema.Struct<{
+    /** An occurrence's `data`, leaving room under a 256 KiB delivery for its envelope. */
+    readonly maxDataBytes: Schema.Int;
+    readonly maxEventsPerInvocation: Schema.Int;
+    readonly maxDescriptionLength: Schema.Int;
+    readonly maxIdLength: Schema.Int;
+}>;
+export type EventLimits = typeof EventLimits.Type;
+export declare const defaultEventLimits: {
+    readonly maxDataBytes: number;
+    readonly maxEventsPerInvocation: number;
+    readonly maxDescriptionLength: number;
+    readonly maxIdLength: number;
+};
+/** One event as the host reads it from an app's requirements. Both schemas are JSON Schema. */
+export declare const DeclaredEvent: Schema.Struct<{
+    readonly description: Schema.String;
+    /** An object of scalar fields. Subscribers may name any of them to narrow an event. */
+    readonly filters: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    /** The shape of each occurrence's `data`. */
+    readonly payload: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+}>;
+export type DeclaredEvent = typeof DeclaredEvent.Type;
+/** An app's declared events, by name. */
+export declare const DeclaredEvents: Schema.$Record<Schema.String, Schema.Struct<{
+    readonly description: Schema.String;
+    /** An object of scalar fields. Subscribers may name any of them to narrow an event. */
+    readonly filters: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    /** The shape of each occurrence's `data`. */
+    readonly payload: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+}>>;
+export type DeclaredEvents = typeof DeclaredEvents.Type;
+/**
+ * One occurrence an invocation emitted. `id` is the stable identifier subscribers deduplicate on,
+ * such as the provider's delivery ID. `account` is the account the event came from, or null for
+ * an app without accounts.
+ */
+export declare const EmittedEvent: Schema.Struct<{
+    readonly name: Schema.String;
+    readonly id: Schema.String;
+    /** Milliseconds since the epoch when the event happened. */
+    readonly occurredAt: Schema.Int;
+    readonly data: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly filters: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>>;
+    readonly account: Schema.NullOr<Schema.brand<Schema.String, "acc">>;
+}>;
+export type EmittedEvent = typeof EmittedEvent.Type;
+/** What a successful invocation emitted, in order. */
+export declare const EmittedEvents: Schema.$Array<Schema.Struct<{
+    readonly name: Schema.String;
+    readonly id: Schema.String;
+    /** Milliseconds since the epoch when the event happened. */
+    readonly occurredAt: Schema.Int;
+    readonly data: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly filters: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>>;
+    readonly account: Schema.NullOr<Schema.brand<Schema.String, "acc">>;
+}>>;
+/** Native event declaration. Filters are named scalar fields; the payload is any JSON schema. */
+export interface AppEvent {
+    readonly description: string;
+    readonly filters: Readonly<Record<string, Schema.Decoder<unknown>>>;
+    readonly payload: Schema.Decoder<unknown>;
+}
+/** Options for one emitted occurrence. */
+export interface EmitOptions<Filters> {
+    /** Values subscribers filter on. Required when the event declares filters. */
+    readonly filters?: Filters;
+    /**
+     * A stable identifier, such as the provider's delivery or record ID, so a repeated delivery of
+     * the same upstream event is not delivered twice. Defaults to a random ID.
+     */
+    readonly id?: string | undefined;
+    /** When the event happened. Defaults to now. */
+    readonly occurredAt?: Date | number | undefined;
+    /**
+     * The ID of the account the event came from. A webhook handler defaults to its source account,
+     * and an invocation with exactly one account to that account. Name it when there are several.
+     */
+    readonly account?: string | undefined;
+}

package/types/apps/src/contracts/host.d.ts

@@ -19,6 +19,7 @@ import { ElicitationFailed, type ElicitationHandler } from "./elicitation.js";
 export { ElicitationLimits, defaultElicitationLimits, FormElicitation, ElicitationResponse, ElicitationReply, ElicitationFailed, type ElicitationHandler, ApprovalElicitation, ApprovalResponse, approvalElicitation, } from "./elicitation.js";
 export { McpClientLimits, defaultMcpClientLimits } from "./mcp.js";
 export * from "./webhook-protocol.js";
+export * from "./events.js";
 export { AccountId, HttpUrl } from "./schema.js";
 export { OAuthClientAuth, OAuthSecretClientAuth, OAuthTokenRequestFormat, OAuthTokenResponse, } from "./provider.js";
 /**
@@ -36,15 +37,16 @@ export { protocol7, AccountCheckCommand, CredentialHost } from "./protocols/7.js
 export { protocol8 } from "./protocols/8.js";
 export { protocol9 } from "./protocols/9.js";
 export { protocol10, MigrateCommand, MigrateResult } from "./protocols/10.js";
+export { protocol11 } from "./protocols/11.js";
 export { AccountCheckResult, AccountInfo } from "./provider.js";
-import { HostAccountsInvalid, HostDeclarationInvalid, HostEvaluationFailed, HostInputInvalid, HostKindMismatch, HostOperationFailed, HostOperationNotFound, HostOutputInvalid, HostRequestInvalid, HostToolApprovalRequired, HostToolBlocked, HostToolNotFound, HostToolPolicyFailed, McpError, SkillLoadFailed, SkillSources, type InvocationDeadline, ResolvedAccounts, type SkillCatalogResponse, type TrustedToolApproval } from "./protocols/10.js";
-export { DeclaredRequirements, HostRequest } from "./protocols/10.js";
+import { HostAccountsInvalid, HostDeclarationInvalid, HostEvaluationFailed, HostInputInvalid, HostKindMismatch, HostOperationFailed, HostOperationNotFound, HostOutputInvalid, HostRequestInvalid, HostToolApprovalRequired, HostToolBlocked, HostToolNotFound, HostToolPolicyFailed, McpError, SkillLoadFailed, SkillSources, type InvocationDeadline, ResolvedAccounts, type SkillCatalogResponse, type TrustedToolApproval } from "./protocols/11.js";
+export { DeclaredRequirements, HostRequest } from "./protocols/11.js";
 /**
  * The MCP and skill loader failures as they cross the host boundary. Apps throw the author-facing
  * classes from `apps/mcp` and `apps/skills`.
  */
-export { McpError, SkillLoadFailed } from "./protocols/10.js";
-export { DeclaredAuthMethod, DeclaredProvider, ResolvedAccount, ResolvedAccounts, TrustedToolApproval, InvocationDeadline, HostedTool, HostedToolSummary, HostRouterError, HostedRouter, HostedCatalog, HostedCatalogSummary, SkillSources, SkillCatalogResponse, HostRequestInvalid, HostAccountsInvalid, HostDeclarationInvalid, HostEvaluationFailed, HostOperationNotFound, HostOperationFailed, HostToolNotFound, HostKindMismatch, InputProblem, maxInputProblems, HostInputInvalid, HostToolBlocked, HostToolApprovalRequired, HostToolPolicyFailed, HostOutputInvalid, HostError, HostResponse, HostInvocation, } from "./protocols/10.js";
+export { McpError, SkillLoadFailed } from "./protocols/11.js";
+export { DeclaredAuthMethod, DeclaredProvider, ResolvedAccount, ResolvedAccounts, TrustedToolApproval, InvocationDeadline, HostedTool, HostedToolSummary, HostRouterError, HostedRouter, HostedCatalog, HostedCatalogSummary, SkillSources, SkillCatalogResponse, HostRequestInvalid, HostAccountsInvalid, HostDeclarationInvalid, HostEvaluationFailed, HostOperationNotFound, HostOperationFailed, HostToolNotFound, HostKindMismatch, InputProblem, maxInputProblems, HostInputInvalid, HostToolBlocked, HostToolApprovalRequired, HostToolPolicyFailed, HostOutputInvalid, HostError, HostResponse, HostInvocation, } from "./protocols/11.js";
 /** Raw host inputs; the host boundary parses and redacts these immediately. */
 export type ResolvedAccountsInput = typeof ResolvedAccounts.Encoded;
 /** Trusted invocation context, supplied separately from the Request. */

package/types/apps/src/contracts/protocol-version.d.ts

@@ -1,6 +1,6 @@
 /**
  * The host protocol this framework speaks. It is written into `runtime.json` and every host
- * snapshot. Released protocols are frozen: see `protocols/10.ts` and notes/apps-publishing.md.
+ * snapshot. Released protocols are frozen: see `protocols/11.ts` and notes/apps-publishing.md.
  * This file has no imports so the package build script can read it directly.
  */
-export declare const frameworkProtocol = 10;
+export declare const frameworkProtocol = 11;