@xfey/tutti 0.1.104 → 0.1.106

package/node_modules/@tutti/shared/dist/schemas/internal/platform-integration.js

@@ -1,6 +1,7 @@
 import { Type } from "@sinclair/typebox";
 import { Value } from "@sinclair/typebox/value";
 import { IdempotencyKeySchema, IsoDateTimeStringSchema, MessageIdSchema, RelayAccountRefSchema, RelayProjectRefSchema, } from "../domain/index.js";
+import { MAX_REFERENCE_STAGED_UPLOAD_BYTES, PresignedUploadPutSchema, ReferenceStagedUploadReferenceProperties, RelayUploadProjectionSchema, } from "../api/uploads.js";
 export const PlatformAdapterKeySchema = Type.String({
     minLength: 1,
     maxLength: 64,
@@ -52,6 +53,7 @@ export const TrustedHumanIntegrationActorContextSchema = Type.Object({
         Type.Literal("platform_chat"),
         Type.Literal("platform_h5"),
         Type.Literal("platform_card_callback"),
+        Type.Literal("platform_document_sync"),
     ]),
     external_subject: ExternalSubjectLocatorSchema,
     binding_ref: IntegrationOwnedRefSchema,
@@ -116,11 +118,19 @@ export const ExternalAttachmentDescriptorSchema = Type.Object({
 }, { additionalProperties: false });
 export const VerifiedAttachmentContentMetadataSchema = Type.Object({
     attachment: ExternalAttachmentDescriptorSchema,
-    size_bytes: Type.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER }),
+    size_bytes: Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER }),
     sha256: Type.String({ pattern: "^sha256:[0-9a-f]{64}$" }),
     media_type: Type.String({ minLength: 1, maxLength: 255 }),
     verified_at: IsoDateTimeStringSchema,
 }, { additionalProperties: false });
+export const PreIdentityReferenceAttachmentSourceSchema = Type.Object({
+    locator: ExternalMessageLocatorSchema,
+    author: PreIdentityConversationAuthorSchema,
+    attachment: ExternalAttachmentDescriptorSchema,
+    external_created_at: IsoDateTimeStringSchema,
+    observed_at: IsoDateTimeStringSchema,
+    adapter_version: Type.String({ minLength: 1, maxLength: 128 }),
+}, { additionalProperties: false });
 export const NormalizedConversationSourceSchema = Type.Object({
     locator: ExternalMessageLocatorSchema,
     revision_ref: ExternalObjectRefSchema,
@@ -221,7 +231,11 @@ export const IntegrationDeliveryDispositionSchema = Type.Union([
     Type.Object({
         kind: Type.Literal("host_incompatible"),
         retryable: Type.Literal(true),
-        reason_code: Type.Literal("integration_source_ingestion_unsupported"),
+        reason_code: Type.Union([
+            Type.Literal("integration_source_ingestion_unsupported"),
+            Type.Literal("integration_attachment_ingestion_unsupported"),
+            Type.Literal("integration_managed_reference_ingestion_unsupported"),
+        ]),
     }, { additionalProperties: false }),
     Type.Object({
         kind: Type.Literal("invalid"),
@@ -236,6 +250,39 @@ export const IntegrationConversationSourceDeliveryRequestSchema = Type.Object({
     receipt: InboundIntegrationEventReceiptSchema,
     source: PreIdentityNormalizedConversationSourceSchema,
 }, { additionalProperties: false });
+export const IntegrationReferenceAttachmentStageRequestSchema = Type.Object({
+    protocol_version: Type.Literal(1),
+    command_id: IdempotencyKeySchema,
+    relay_project_ref: RelayProjectRefSchema,
+    binding_ref: IntegrationOwnedRefSchema,
+    receipt: InboundIntegrationEventReceiptSchema,
+    source: PreIdentityReferenceAttachmentSourceSchema,
+    content: VerifiedAttachmentContentMetadataSchema,
+}, { additionalProperties: false });
+export const IntegrationReferenceAttachmentStageDispositionSchema = Type.Union([
+    Type.Object({
+        kind: Type.Literal("staged"),
+        upload: RelayUploadProjectionSchema,
+        put: PresignedUploadPutSchema,
+    }, { additionalProperties: false }),
+    Type.Object({
+        kind: Type.Literal("unauthorized"),
+        reason_code: Type.String({ minLength: 1, maxLength: 128 }),
+    }, { additionalProperties: false }),
+    Type.Object({
+        kind: Type.Literal("invalid"),
+        reason_code: Type.String({ minLength: 1, maxLength: 128 }),
+    }, { additionalProperties: false }),
+    Type.Object({
+        kind: Type.Literal("unavailable"),
+        retryable: Type.Literal(true),
+        reason_code: Type.String({ minLength: 1, maxLength: 128 }),
+    }, { additionalProperties: false }),
+]);
+export const IntegrationReferenceAttachmentStageResponseSchema = Type.Object({
+    protocol_version: Type.Literal(1),
+    disposition: IntegrationReferenceAttachmentStageDispositionSchema,
+}, { additionalProperties: false });
 export const FEISHU_CONVERSATION_PAIRING_CODE_LENGTH = 20;
 export const FeishuConversationPairingCodeSchema = Type.String({
     minLength: FEISHU_CONVERSATION_PAIRING_CODE_LENGTH,
@@ -296,6 +343,106 @@ export const IntegrationConversationBindingResponseSchema = Type.Object({
     disposition: IntegrationConversationBindingDispositionSchema,
 }, { additionalProperties: false });
 export const INTEGRATION_CONVERSATION_SOURCE_TUNNEL_PATH = "/internal/integration/v1/conversation-sources";
+export const INTEGRATION_REFERENCE_ATTACHMENT_TUNNEL_PATH = "/internal/integration/v1/reference-attachments";
+export const INTEGRATION_MANAGED_REFERENCE_TUNNEL_PATH = "/internal/integration/v1/managed-references";
+export const ManagedReferenceSourceSchema = Type.Object({
+    source_ref: IntegrationOwnedRefSchema,
+    adapter_key: Type.Literal("feishu_docx"),
+    installation: PlatformInstallationLocatorSchema,
+    external_subject: ExternalSubjectLocatorSchema,
+    reference_path: Type.String({ minLength: 1, maxLength: 1_024 }),
+}, { additionalProperties: false });
+export const ManagedReferenceContentMetadataSchema = Type.Object({
+    size_bytes: Type.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER }),
+    sha256: Type.String({ pattern: "^sha256:[0-9a-f]{64}$" }),
+    media_type: Type.Literal("text/plain; charset=utf-8"),
+}, { additionalProperties: false });
+export const IntegrationManagedReferenceStageRequestSchema = Type.Object({
+    protocol_version: Type.Literal(1),
+    command_id: IdempotencyKeySchema,
+    operation_ref: IntegrationOwnedRefSchema,
+    relay_project_ref: RelayProjectRefSchema,
+    binding_ref: IntegrationOwnedRefSchema,
+    source: ManagedReferenceSourceSchema,
+    remote_revision_ref: ExternalObjectRefSchema,
+    expected_host_blob_oid: Type.Optional(Type.String({ pattern: "^[0-9a-f]{40,64}$" })),
+    content: ManagedReferenceContentMetadataSchema,
+}, { additionalProperties: false });
+export const IntegrationManagedReferenceStageDispositionSchema = IntegrationReferenceAttachmentStageDispositionSchema;
+export const IntegrationManagedReferenceStageResponseSchema = Type.Object({
+    protocol_version: Type.Literal(1),
+    disposition: IntegrationManagedReferenceStageDispositionSchema,
+}, { additionalProperties: false });
+export const IntegrationManagedReferenceDeliveryRequestSchema = Type.Object({
+    protocol_version: Type.Literal(1),
+    command_id: IdempotencyKeySchema,
+    operation_ref: IntegrationOwnedRefSchema,
+    relay_project_ref: RelayProjectRefSchema,
+    binding_ref: IntegrationOwnedRefSchema,
+    source: ManagedReferenceSourceSchema,
+    remote_revision_ref: ExternalObjectRefSchema,
+    expected_host_blob_oid: Type.Optional(Type.String({ pattern: "^[0-9a-f]{40,64}$" })),
+    content: ManagedReferenceContentMetadataSchema,
+    staged_upload: Type.Object(ReferenceStagedUploadReferenceProperties, {
+        additionalProperties: false,
+    }),
+}, { additionalProperties: false });
+export const TrustedManagedReferenceIngestionCommandSchema = Type.Object({
+    protocol_version: Type.Literal(1),
+    command_id: IdempotencyKeySchema,
+    operation_ref: IntegrationOwnedRefSchema,
+    relay_project_ref: RelayProjectRefSchema,
+    binding_ref: IntegrationOwnedRefSchema,
+    source: ManagedReferenceSourceSchema,
+    remote_revision_ref: ExternalObjectRefSchema,
+    expected_host_blob_oid: Type.Optional(Type.String({ pattern: "^[0-9a-f]{40,64}$" })),
+    content: ManagedReferenceContentMetadataSchema,
+    staged_upload: Type.Object(ReferenceStagedUploadReferenceProperties, {
+        additionalProperties: false,
+    }),
+    actor: TrustedHumanIntegrationActorContextSchema,
+}, { additionalProperties: false });
+export const IntegrationManagedReferenceDispositionSchema = Type.Union([
+    Type.Object({
+        kind: Type.Union([
+            Type.Literal("created"),
+            Type.Literal("updated"),
+            Type.Literal("unchanged"),
+        ]),
+        current_blob_oid: Type.String({ pattern: "^[0-9a-f]{40,64}$" }),
+    }, { additionalProperties: false }),
+    Type.Object({
+        kind: Type.Literal("duplicate"),
+        outcome: Type.Union([
+            Type.Literal("created"),
+            Type.Literal("updated"),
+            Type.Literal("unchanged"),
+        ]),
+        current_blob_oid: Type.String({ pattern: "^[0-9a-f]{40,64}$" }),
+    }, { additionalProperties: false }),
+    Type.Object({
+        kind: Type.Literal("host_unavailable"),
+        retryable: Type.Literal(true),
+        reason_code: Type.String({ minLength: 1, maxLength: 128 }),
+    }, { additionalProperties: false }),
+    Type.Object({
+        kind: Type.Literal("host_incompatible"),
+        retryable: Type.Literal(true),
+        reason_code: Type.Literal("integration_managed_reference_ingestion_unsupported"),
+    }, { additionalProperties: false }),
+    Type.Object({
+        kind: Type.Union([
+            Type.Literal("invalid"),
+            Type.Literal("unauthorized"),
+            Type.Literal("conflict"),
+        ]),
+        reason_code: Type.String({ minLength: 1, maxLength: 128 }),
+    }, { additionalProperties: false }),
+]);
+export const IntegrationManagedReferenceDeliveryResponseSchema = Type.Object({
+    protocol_version: Type.Literal(1),
+    disposition: IntegrationManagedReferenceDispositionSchema,
+}, { additionalProperties: false });
 export const TrustedConversationSourceIngestionCommandSchema = Type.Object({
     protocol_version: Type.Literal(1),
     command_id: IdempotencyKeySchema,
@@ -305,14 +452,47 @@ export const TrustedConversationSourceIngestionCommandSchema = Type.Object({
     actor: TrustedHumanIntegrationActorContextSchema,
     source: NormalizedConversationSourceSchema,
 }, { additionalProperties: false });
-export const IntegrationDeliveryTunnelMetadataSchema = Type.Object({
+export const IntegrationReferenceAttachmentDeliveryRequestSchema = Type.Object({
     protocol_version: Type.Literal(1),
+    command_id: IdempotencyKeySchema,
     relay_project_ref: RelayProjectRefSchema,
-    installation: PlatformInstallationLocatorSchema,
     binding_ref: IntegrationOwnedRefSchema,
-    receipt_key: IntegrationOwnedRefSchema,
-    verified_at: IsoDateTimeStringSchema,
+    receipt: InboundIntegrationEventReceiptSchema,
+    source: PreIdentityReferenceAttachmentSourceSchema,
+    staged_upload: Type.Object(ReferenceStagedUploadReferenceProperties, {
+        additionalProperties: false,
+    }),
 }, { additionalProperties: false });
+export const TrustedReferenceAttachmentIngestionCommandSchema = Type.Object({
+    protocol_version: Type.Literal(1),
+    command_id: IdempotencyKeySchema,
+    relay_project_ref: RelayProjectRefSchema,
+    binding_ref: IntegrationOwnedRefSchema,
+    receipt: InboundIntegrationEventReceiptSchema,
+    actor: TrustedHumanIntegrationActorContextSchema,
+    source: PreIdentityReferenceAttachmentSourceSchema,
+    staged_upload: Type.Object(ReferenceStagedUploadReferenceProperties, {
+        additionalProperties: false,
+    }),
+}, { additionalProperties: false });
+export const IntegrationDeliveryTunnelMetadataSchema = Type.Union([
+    Type.Object({
+        protocol_version: Type.Literal(1),
+        relay_project_ref: RelayProjectRefSchema,
+        installation: PlatformInstallationLocatorSchema,
+        binding_ref: IntegrationOwnedRefSchema,
+        receipt_key: IntegrationOwnedRefSchema,
+        verified_at: IsoDateTimeStringSchema,
+    }, { additionalProperties: false }),
+    Type.Object({
+        protocol_version: Type.Literal(1),
+        relay_project_ref: RelayProjectRefSchema,
+        installation: PlatformInstallationLocatorSchema,
+        binding_ref: IntegrationOwnedRefSchema,
+        operation_ref: IntegrationOwnedRefSchema,
+        verified_at: IsoDateTimeStringSchema,
+    }, { additionalProperties: false }),
+]);
 export const IntegrationConversationSourceDeliveryResponseSchema = Type.Object({
     protocol_version: Type.Literal(1),
     disposition: IntegrationDeliveryDispositionSchema,
@@ -321,25 +501,149 @@ const PlatformOutboundTextContentSchema = Type.Object({
     kind: Type.Literal("text"),
     text: Type.String({ minLength: 1, maxLength: 4_000 }),
 }, { additionalProperties: false });
+export const PlatformApprovalCardRevisionSchema = Type.String({
+    minLength: 1,
+    maxLength: 128,
+    pattern: "^cardrev_[0-9a-f]{32}$",
+});
+export const PlatformApprovalDecisionOptionSchema = Type.Object({
+    decision_id: Type.String({ minLength: 1, maxLength: 256 }),
+    kind: Type.Union([
+        Type.Literal("allow_once"),
+        Type.Literal("allow_session"),
+        Type.Literal("deny"),
+        Type.Literal("cancel"),
+    ]),
+    label: Type.String({ minLength: 1, maxLength: 256 }),
+    tone: Type.Union([Type.Literal("primary"), Type.Literal("neutral"), Type.Literal("danger")]),
+}, { additionalProperties: false });
+export const PlatformOutboundApprovalRequestContentSchema = Type.Object({
+    kind: Type.Literal("approval_request"),
+    approval_id: Type.String({ minLength: 1, maxLength: 256 }),
+    card_revision: PlatformApprovalCardRevisionSchema,
+    title: Type.String({ minLength: 1, maxLength: 512 }),
+    summary: Type.String({ minLength: 1, maxLength: 4_000 }),
+    reason: Type.Optional(Type.String({ minLength: 1, maxLength: 2_000 })),
+    requested_at: IsoDateTimeStringSchema,
+    expires_at: Type.Optional(IsoDateTimeStringSchema),
+    decisions: Type.Array(PlatformApprovalDecisionOptionSchema, {
+        minItems: 1,
+        maxItems: 8,
+    }),
+}, { additionalProperties: false });
+export const PlatformOutboundContentSchema = Type.Union([
+    PlatformOutboundTextContentSchema,
+    PlatformOutboundApprovalRequestContentSchema,
+]);
+export const PlatformOutboundEventSchema = Type.Object({
+    kind: Type.Union([
+        Type.Literal("chat_response"),
+        Type.Literal("needs_input"),
+        Type.Literal("task_completed"),
+        Type.Literal("task_failed"),
+    ]),
+    event_key: ExternalObjectRefSchema,
+    subject: Type.Object({
+        kind: Type.Union([
+            Type.Literal("message"),
+            Type.Literal("clarification_round"),
+            Type.Literal("approval_request"),
+            Type.Literal("task_result"),
+        ]),
+        ref: ExternalObjectRefSchema,
+    }, { additionalProperties: false }),
+    target: Type.Object({
+        kind: Type.Union([Type.Literal("project"), Type.Literal("work")]),
+    }, { additionalProperties: false }),
+}, { additionalProperties: false });
 const PlatformOutboundIntentFields = {
     protocol_version: Type.Literal(1),
     intent_ref: IdempotencyKeySchema,
     relay_project_ref: RelayProjectRefSchema,
     installation: PlatformInstallationLocatorSchema,
     binding_ref: IntegrationOwnedRefSchema,
-    canonical_message_ref: MessageIdSchema,
-    trigger_message_ref: MessageIdSchema,
-    content: PlatformOutboundTextContentSchema,
+    canonical_message_ref: Type.Optional(MessageIdSchema),
+    trigger_message_ref: Type.Optional(MessageIdSchema),
+    content: PlatformOutboundContentSchema,
+    event: Type.Optional(PlatformOutboundEventSchema),
     created_at: IsoDateTimeStringSchema,
     attempt: Type.Integer({ minimum: 1, maximum: 1_000_000 }),
 };
-export const PlatformOutboundTextIntentSchema = Type.Object(PlatformOutboundIntentFields, {
+export const PlatformOutboundIntentSchema = Type.Object(PlatformOutboundIntentFields, {
     additionalProperties: false,
 });
-export const RelayAuthorizedPlatformOutboundTextIntentSchema = Type.Object({
+export const RelayAuthorizedPlatformOutboundIntentSchema = Type.Object({
     ...PlatformOutboundIntentFields,
     conversation_ref: ExternalObjectRefSchema,
 }, { additionalProperties: false });
+// Compatibility aliases for the original text-only contract name. The schema now
+// carries either text or a structured approval request.
+export const PlatformOutboundTextIntentSchema = PlatformOutboundIntentSchema;
+export const RelayAuthorizedPlatformOutboundTextIntentSchema = RelayAuthorizedPlatformOutboundIntentSchema;
+export const PlatformCardCallbackSchema = Type.Object({
+    conversation_ref: ExternalObjectRefSchema,
+    message_ref: ExternalObjectRefSchema,
+    action_ref: IntegrationOwnedRefSchema,
+    card_revision: PlatformApprovalCardRevisionSchema,
+    external_subject: ExternalSubjectLocatorSchema,
+}, { additionalProperties: false });
+export const IntegrationApprovalDecisionDeliveryRequestSchema = Type.Object({
+    protocol_version: Type.Literal(1),
+    command_id: IdempotencyKeySchema,
+    relay_project_ref: RelayProjectRefSchema,
+    binding_ref: IntegrationOwnedRefSchema,
+    receipt: InboundIntegrationEventReceiptSchema,
+    callback: PlatformCardCallbackSchema,
+    approval_id: Type.String({ minLength: 1, maxLength: 256 }),
+    decision_id: Type.String({ minLength: 1, maxLength: 256 }),
+}, { additionalProperties: false });
+export const TrustedApprovalDecisionCommandSchema = Type.Object({
+    protocol_version: Type.Literal(1),
+    command_id: IdempotencyKeySchema,
+    relay_project_ref: RelayProjectRefSchema,
+    binding_ref: IntegrationOwnedRefSchema,
+    receipt: InboundIntegrationEventReceiptSchema,
+    actor: TrustedHumanIntegrationActorContextSchema,
+    callback: Type.Object({
+        message_ref: ExternalObjectRefSchema,
+        action_ref: IntegrationOwnedRefSchema,
+        card_revision: PlatformApprovalCardRevisionSchema,
+    }, { additionalProperties: false }),
+    approval_id: Type.String({ minLength: 1, maxLength: 256 }),
+    decision_id: Type.String({ minLength: 1, maxLength: 256 }),
+}, { additionalProperties: false });
+export const IntegrationApprovalDecisionDispositionSchema = Type.Union([
+    Type.Object({ kind: Type.Literal("accepted") }, { additionalProperties: false }),
+    Type.Object({ kind: Type.Literal("stale_approval") }, { additionalProperties: false }),
+    Type.Object({ kind: Type.Literal("decision_unavailable") }, { additionalProperties: false }),
+    Type.Object({
+        kind: Type.Literal("interrupted"),
+        retry_with_new_command_id: Type.Boolean(),
+    }, { additionalProperties: false }),
+    Type.Object({
+        kind: Type.Literal("unauthorized"),
+        reason_code: Type.String({ minLength: 1, maxLength: 128 }),
+    }, { additionalProperties: false }),
+    Type.Object({
+        kind: Type.Literal("invalid"),
+        reason_code: Type.String({ minLength: 1, maxLength: 128 }),
+    }, { additionalProperties: false }),
+    Type.Object({
+        kind: Type.Literal("host_unavailable"),
+        retryable: Type.Literal(true),
+        reason_code: Type.String({ minLength: 1, maxLength: 128 }),
+    }, { additionalProperties: false }),
+    Type.Object({
+        kind: Type.Literal("host_incompatible"),
+        retryable: Type.Literal(true),
+        reason_code: Type.Literal("integration_approval_decision_unsupported"),
+    }, { additionalProperties: false }),
+]);
+export const IntegrationApprovalDecisionDeliveryResponseSchema = Type.Object({
+    protocol_version: Type.Literal(1),
+    disposition: IntegrationApprovalDecisionDispositionSchema,
+}, { additionalProperties: false });
+export const INTEGRATION_APPROVAL_DECISION_TUNNEL_PATH = "/internal/integration/v1/approval-decisions";
 export const IntegrationOutboundClaimRequestSchema = Type.Object({
     protocol_version: Type.Literal(1),
     installation: PlatformInstallationLocatorSchema,
@@ -358,7 +662,7 @@ export const IntegrationOutboundClaimResponseSchema = Type.Union([
             kind: Type.Literal("claimed"),
             claim_ref: IntegrationOwnedRefSchema,
             claim_expires_at: IsoDateTimeStringSchema,
-            intent: RelayAuthorizedPlatformOutboundTextIntentSchema,
+            intent: RelayAuthorizedPlatformOutboundIntentSchema,
         }, { additionalProperties: false }),
     }, { additionalProperties: false }),
 ]);
@@ -457,6 +761,83 @@ export function isIntegrationConversationSourceDeliveryRequest(value) {
         sameInstallation(request.receipt.installation, sourceInstallation) &&
         sameInstallation(request.receipt.installation, sourceSubject.installation));
 }
+function sameAttachment(left, right) {
+    return (left.attachment_ref === right.attachment_ref &&
+        left.attachment_kind === right.attachment_kind &&
+        left.file_name === right.file_name &&
+        left.media_type === right.media_type);
+}
+function validPreIdentityReferenceAttachmentAuthority(value) {
+    return (value.receipt.event_kind === "attachment" &&
+        value.source.author.external_subject.subject_kind === "human" &&
+        sameInstallation(value.receipt.installation, value.source.locator.conversation.installation) &&
+        sameInstallation(value.receipt.installation, value.source.author.external_subject.installation));
+}
+export function isIntegrationReferenceAttachmentStageRequest(value) {
+    return (Value.Check(IntegrationReferenceAttachmentStageRequestSchema, value) &&
+        validPreIdentityReferenceAttachmentAuthority(value) &&
+        sameAttachment(value.source.attachment, value.content.attachment) &&
+        value.content.attachment.file_name !== undefined);
+}
+export function isIntegrationReferenceAttachmentStageResponse(value) {
+    return Value.Check(IntegrationReferenceAttachmentStageResponseSchema, value);
+}
+export function isIntegrationReferenceAttachmentDeliveryRequest(value) {
+    return (Value.Check(IntegrationReferenceAttachmentDeliveryRequestSchema, value) &&
+        validPreIdentityReferenceAttachmentAuthority(value) &&
+        value.source.attachment.file_name === value.staged_upload.file_name &&
+        value.source.attachment.media_type === value.staged_upload.media_type);
+}
+function validManagedReferenceSource(value) {
+    return (value.source_ref.startsWith("managed_ref_") &&
+        value.installation.platform === "feishu" &&
+        value.external_subject.subject_kind === "human" &&
+        sameInstallation(value.installation, value.external_subject.installation) &&
+        value.reference_path.startsWith("docs/reference/") &&
+        !value.reference_path.includes("\\") &&
+        !value.reference_path
+            .split("/")
+            .some((segment) => segment.length === 0 || segment === "." || segment === ".."));
+}
+function validManagedReferenceContent(value) {
+    return value.size_bytes <= MAX_REFERENCE_STAGED_UPLOAD_BYTES;
+}
+function sameManagedReferenceStageContent(value) {
+    return (value.content.size_bytes === value.staged_upload.size_bytes &&
+        value.content.sha256 === value.staged_upload.sha256 &&
+        value.content.media_type === value.staged_upload.media_type &&
+        value.staged_upload.file_name === value.source.reference_path.split("/").at(-1));
+}
+export function isIntegrationManagedReferenceStageRequest(value) {
+    return (Value.Check(IntegrationManagedReferenceStageRequestSchema, value) &&
+        validManagedReferenceSource(value.source) &&
+        validManagedReferenceContent(value.content));
+}
+export function isIntegrationManagedReferenceStageResponse(value) {
+    return Value.Check(IntegrationManagedReferenceStageResponseSchema, value);
+}
+export function isIntegrationManagedReferenceDeliveryRequest(value) {
+    return (Value.Check(IntegrationManagedReferenceDeliveryRequestSchema, value) &&
+        validManagedReferenceSource(value.source) &&
+        validManagedReferenceContent(value.content) &&
+        sameManagedReferenceStageContent(value));
+}
+export function isTrustedManagedReferenceIngestionCommand(value) {
+    if (!Value.Check(TrustedManagedReferenceIngestionCommandSchema, value)) {
+        return false;
+    }
+    return (validManagedReferenceSource(value.source) &&
+        validManagedReferenceContent(value.content) &&
+        sameManagedReferenceStageContent(value) &&
+        value.actor.channel === "platform_document_sync" &&
+        value.actor.external_subject.subject_ref === value.source.external_subject.subject_ref &&
+        sameInstallation(value.actor.external_subject.installation, value.source.installation) &&
+        value.actor.binding_ref === value.binding_ref &&
+        value.actor.membership.relay_project_ref === value.relay_project_ref);
+}
+export function isIntegrationManagedReferenceDeliveryResponse(value) {
+    return Value.Check(IntegrationManagedReferenceDeliveryResponseSchema, value);
+}
 export function isIntegrationConversationBindingRequest(value) {
     if (!Value.Check(IntegrationConversationBindingRequestSchema, value)) {
         return false;
@@ -484,17 +865,56 @@ export function isTrustedConversationSourceIngestionCommand(value) {
         sameInstallation(command.receipt.installation, sourceInstallation) &&
         sameInstallation(command.receipt.installation, sourceAuthor.external_subject.installation));
 }
+export function isTrustedReferenceAttachmentIngestionCommand(value) {
+    if (!Value.Check(TrustedReferenceAttachmentIngestionCommandSchema, value)) {
+        return false;
+    }
+    return (validPreIdentityReferenceAttachmentAuthority(value) &&
+        value.actor.channel === "platform_chat" &&
+        value.actor.membership.relay_project_ref === value.relay_project_ref &&
+        value.actor.binding_ref === value.binding_ref &&
+        sameExternalSubject(value.actor.external_subject, value.source.author.external_subject) &&
+        value.source.attachment.file_name === value.staged_upload.file_name &&
+        value.source.attachment.media_type === value.staged_upload.media_type);
+}
 export function isIntegrationDeliveryTunnelMetadata(value) {
     return Value.Check(IntegrationDeliveryTunnelMetadataSchema, value);
 }
 export function isIntegrationConversationSourceDeliveryResponse(value) {
     return Value.Check(IntegrationConversationSourceDeliveryResponseSchema, value);
 }
+export function isIntegrationApprovalDecisionDeliveryRequest(value) {
+    if (!Value.Check(IntegrationApprovalDecisionDeliveryRequestSchema, value)) {
+        return false;
+    }
+    return (value.receipt.event_kind === "card_action" &&
+        value.callback.external_subject.subject_kind === "human" &&
+        sameInstallation(value.receipt.installation, value.callback.external_subject.installation));
+}
+export function isTrustedApprovalDecisionCommand(value) {
+    if (!Value.Check(TrustedApprovalDecisionCommandSchema, value)) {
+        return false;
+    }
+    return (value.receipt.event_kind === "card_action" &&
+        value.actor.channel === "platform_card_callback" &&
+        value.actor.membership.relay_project_ref === value.relay_project_ref &&
+        value.actor.binding_ref === value.binding_ref &&
+        sameInstallation(value.receipt.installation, value.actor.external_subject.installation));
+}
+export function isIntegrationApprovalDecisionDeliveryResponse(value) {
+    return Value.Check(IntegrationApprovalDecisionDeliveryResponseSchema, value);
+}
 export function isPlatformOutboundTextIntent(value) {
-    return Value.Check(PlatformOutboundTextIntentSchema, value);
+    return Value.Check(PlatformOutboundIntentSchema, value);
+}
+export function isPlatformOutboundIntent(value) {
+    return Value.Check(PlatformOutboundIntentSchema, value);
 }
 export function isRelayAuthorizedPlatformOutboundTextIntent(value) {
-    return Value.Check(RelayAuthorizedPlatformOutboundTextIntentSchema, value);
+    return Value.Check(RelayAuthorizedPlatformOutboundIntentSchema, value);
+}
+export function isRelayAuthorizedPlatformOutboundIntent(value) {
+    return Value.Check(RelayAuthorizedPlatformOutboundIntentSchema, value);
 }
 export function isIntegrationOutboundClaimRequest(value) {
     return (Value.Check(IntegrationOutboundClaimRequestSchema, value) &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xfey/tutti",
-  "version": "0.1.104",
+  "version": "0.1.106",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/prompts/skills/read-references/README.md

@@ -2,7 +2,7 @@
 
 Built-in Codex context access skill for reading Tutti reference files.
 
-This skill covers reference listing, existing summary metadata, and text file reads. It is selected only by app-server turns whose server-side configuration grants `references:list` and, when file text is needed, `references:read`.
+This skill covers reference listing, existing summary metadata, and text file reads. The same capability reads ordinary repo References and Host-managed external document snapshots; platform synchronization remains outside the model-facing skill. It is selected only by app-server turns whose server-side configuration grants `references:list` and, when file text is needed, `references:read`.
 
 The skill remains read-only. It can return summary fields produced elsewhere, but it never creates, refreshes, or writes summaries.
 

package/prompts/skills/read-references/SKILL.md

@@ -5,7 +5,7 @@ description: List and read bounded Tutti reference files when the turn has refer
 
 # Read References
 
-Use this skill when a Tutti app-server turn needs material from the shared project Reference space. Files may have been uploaded by a project member or created by Tutti in an earlier Run.
+Use this skill when a Tutti app-server turn needs material from the shared project Reference space. References may be ordinary files uploaded by a project member, files created by Tutti in an earlier Run, or Host-managed snapshots of an external document. The Host snapshot is the only readable content authority for this skill; do not call the external platform directly or infer that its remote revision is current.
 
 When a Tutti context API runtime hint is present and includes `references:list`, list available references through:
 
@@ -13,6 +13,8 @@ When a Tutti context API runtime hint is present and includes `references:list`,
 
 List items may include a `summary` object with `status`, optional `text`, `generated_at`, `source_blob_oid`, `unavailable_reason`, and `read_paths`. Treat this summary as orientation only. It can be missing, stale, or unavailable, and it does not replace reading a relevant file.
 
+For a managed snapshot, `stale` means the saved summary belongs to an older local content blob. Read the current file when it matters, even while its replacement summary is still pending. It does not mean this API has checked the external platform for a newer remote revision.
+
 When a listed text file is relevant and the hint includes `references:read`, read it through:
 
 `GET {base_url}/references/file?path=...&max_bytes=...`
@@ -21,6 +23,6 @@ Read responses may include the same `summary` object alongside text or unavailab
 
 Read only reference files that are relevant to the current task or question. Do not infer file contents from creation events, names, media types, paths, or summaries alone. If a file is unavailable, restricted, binary, too large, or unsupported, use the returned disposition instead of guessing.
 
-This skill is read-only. Do not attempt to create, update, refresh, or write reference summaries from this skill.
+This skill is read-only. Do not attempt to create, synchronize, update, refresh, or write Reference content or summaries from this skill.
 
 Never expose the context API token, base URL, raw large responses, host paths, credentials, cookies, provider details, or private reference excerpts beyond what is necessary for the final structured output.