@danceiny/gotry 0.0.1-rc.16 → 0.0.1-rc.18

package/schemas/booking.surface.v2.schema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://gotry.dev/schemas/booking.surface.v2.schema.json",
+  "oneOf": [
+    {"$ref":"#/$defs/Workspace"},{"$ref":"#/$defs/Action"},{"$ref":"#/$defs/Receipt"},
+    {"$ref":"#/$defs/Ingress"},{"$ref":"#/$defs/UserTurn"},{"$ref":"#/$defs/Continuation"},{"$ref":"#/$defs/Event"}
+  ],
+  "$defs": {
+    "Ref":{"$ref":"https://gotry.dev/schemas/booking.surface.v1.schema.json#/$defs/OpaqueRef"},
+    "Hex64":{"type":"string","pattern":"^[0-9a-f]{64}$"},
+    "Surface":{"enum":["tenant","customer_portal","storefront","payment_link"]},
+    "Kind":{"enum":["search.patch","search.run","results.view.patch","hotel.focus","hotel.select","offers.query","offers.view.patch","offers.compare","offer.select","offer.check","checkout.prepare","order.observe"]},
+    "Codes":{"type":"array","minItems":0,"maxItems":28,"uniqueItems":true,"items":{"enum":["byos_mapped_risk","check_avail_failed","check_avail_unverified","component_executor_unavailable","hotel_not_visible","hotel_rates_failed","offer_facts_changed","offer_not_loaded","offer_unavailable","order_not_found","order_outcome_not_observed","order_state_unknown","order_status_unavailable","requested_offers_not_loaded","search_failed","search_form_invalid","search_session_expired","search_terminal_timeout","stale_revision","surface_adapter_failed","undo_token_not_found","unhandled","unsupported","verified_offer_required","workspace_changed_during_action","criterion_must_not_met","no_hotels_matched","offer_target_not_reached"]}},
+    "LoadedOffer":{"type":"object","additionalProperties":false,"required":["offerRef","offerVersionRef","hotelRef","evidenceLevel","factRefs"],"properties":{"offerRef":{"$ref":"#/$defs/Ref"},"offerVersionRef":{"$ref":"#/$defs/Ref"},"hotelRef":{"$ref":"#/$defs/Ref"},"evidenceLevel":{"enum":["listed","rate_loaded","checked"]},"factRefs":{"type":"array","maxItems":64,"uniqueItems":true,"items":{"$ref":"#/$defs/Ref"}}}},
+    "VerifiedOffer":{"type":"object","additionalProperties":false,"required":["offerRef","offerVersionRef","verifiedOfferRef","expiresAt"],"properties":{"offerRef":{"$ref":"#/$defs/Ref"},"offerVersionRef":{"$ref":"#/$defs/Ref"},"verifiedOfferRef":{"$ref":"#/$defs/Ref"},"expiresAt":{"type":"string","pattern":"^\\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\\d|3[01])T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,9})?(?:Z|[+-](?:[01]\\d|2[0-3]):[0-5]\\d)$"}}},
+    "OfferVersionInput":{"type":"object","additionalProperties":false,"required":["offerRef","offerVersionRef"],"properties":{"offerRef":{"$ref":"#/$defs/Ref"},"offerVersionRef":{"$ref":"#/$defs/Ref"}}},
+    "CheckoutPrepareVersionInput":{"type":"object","additionalProperties":false,"required":["offerRef","offerVersionRef","verifiedOfferRef"],"properties":{"offerRef":{"$ref":"#/$defs/Ref"},"offerVersionRef":{"$ref":"#/$defs/Ref"},"verifiedOfferRef":{"$ref":"#/$defs/Ref"}}},
+    "Workspace":{"type":"object","additionalProperties":false,"required":["schemaVersion","contextRef","surface","revision","locale","currency","searchDraft","results","visibleHotels","loadedOffers","shortlistedOfferRefs","capabilities"],"properties":{"schemaVersion":{"const":"booking.surface.v2"},"contextRef":{"$ref":"#/$defs/Ref"},"surface":{"$ref":"#/$defs/Surface"},"revision":{"$ref":"https://gotry.dev/schemas/booking.surface.v1.schema.json#/$defs/Revision"},"locale":{"$ref":"https://gotry.dev/schemas/booking.surface.v1.schema.json#/$defs/NonEmptyString"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"searchDraft":{"$ref":"https://gotry.dev/schemas/booking.surface.v1.schema.json#/$defs/SearchDraftSnapshotV1"},"results":{"$ref":"https://gotry.dev/schemas/booking.surface.v1.schema.json#/$defs/ResultViewSnapshotV1"},"visibleHotels":{"type":"array","maxItems":100,"items":{"$ref":"https://gotry.dev/schemas/booking.surface.v1.schema.json#/$defs/VisibleHotelFactV1"}},"loadedOffers":{"type":"array","maxItems":200,"items":{"$ref":"#/$defs/LoadedOffer"}},"focusedHotelRef":{"$ref":"#/$defs/Ref"},"shortlistedOfferRefs":{"type":"array","maxItems":100,"uniqueItems":true,"items":{"$ref":"#/$defs/Ref"}},"selectedOfferRef":{"$ref":"#/$defs/Ref"},"verifiedOffer":{"$ref":"#/$defs/VerifiedOffer"},"capabilities":{"type":"object","additionalProperties":false,"required":["surface","allowedActions"],"properties":{"surface":{"$ref":"#/$defs/Surface"},"allowedActions":{"type":"array","minItems":1,"maxItems":12,"uniqueItems":true,"items":{"$ref":"#/$defs/Kind"}}}}}},
+    "IngressWorkspace":{"type":"object","additionalProperties":false,"required":["schemaVersion","revision","locale","currency","searchDraft","results","visibleHotels","loadedOffers","shortlistedOfferRefs"],"properties":{"schemaVersion":{"const":"booking.surface.v2"},"revision":{"type":"integer","minimum":0},"locale":{"type":"string","minLength":1,"maxLength":64},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"searchDraft":{"$ref":"https://gotry.dev/schemas/booking.surface.v1.schema.json#/$defs/SearchDraftSnapshotV1"},"results":{"$ref":"https://gotry.dev/schemas/booking.surface.v1.schema.json#/$defs/ResultViewSnapshotV1"},"visibleHotels":{"type":"array","maxItems":100,"items":{"$ref":"https://gotry.dev/schemas/booking.surface.v1.schema.json#/$defs/VisibleHotelFactV1"}},"loadedOffers":{"type":"array","maxItems":200,"items":{"$ref":"#/$defs/LoadedOffer"}},"focusedHotelRef":{"$ref":"#/$defs/Ref"},"shortlistedOfferRefs":{"type":"array","maxItems":100,"uniqueItems":true,"items":{"$ref":"#/$defs/Ref"}},"selectedOfferRef":{"$ref":"#/$defs/Ref"}}},
+    "PresentationKey":{"type":"string","minLength":1,"maxLength":512},
+    "RequestKey":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9:._-]{7,127}$"},
+    "ApprovalRef":{"type":"object","additionalProperties":false,"required":["approvalId","blockerId","contextRef","sourceTurnId","presentationRequestKey","sourceActionId","targetActionId","sourceRevision","targetActionKind","to","expiresAt","nonce","sourceReceiptDigest","scope","code","criterionPath","valueDigest"],"properties":{"approvalId":{"$ref":"#/$defs/Ref"},"blockerId":{"$ref":"#/$defs/Ref"},"contextRef":{"$ref":"#/$defs/Ref"},"sourceTurnId":{"$ref":"#/$defs/Ref"},"presentationRequestKey":{"$ref":"#/$defs/PresentationKey"},"sourceActionId":{"$ref":"#/$defs/Ref"},"targetActionId":{"$ref":"#/$defs/Ref"},"sourceRevision":{"type":"integer","minimum":0},"targetActionKind":{"$ref":"#/$defs/Kind"},"to":{"enum":["prefer","drop"]},"expiresAt":{"type":"string","minLength":1},"nonce":{"$ref":"#/$defs/Ref"},"sourceReceiptDigest":{"$ref":"#/$defs/Hex64"},"scope":{"enum":["search","offer","availability","checkout"]},"code":{"enum":["no_hotels_matched","hotel_not_visible","hotel_rates_failed","criterion_must_not_met","offer_target_not_reached","offer_unavailable"]},"criterionPath":{"type":"string","pattern":"^(searchDraft|results|offers|checkout)(\\.[A-Za-z][A-Za-z0-9_]*){0,3}$","maxLength":160},"valueDigest":{"$ref":"#/$defs/Hex64"}}},
+    "ActionBase":{"type":"object","additionalProperties":false,"required":["schemaVersion","kind","actionId","contextRef","expectedRevision","reason","factRefs","input"],"properties":{"schemaVersion":{"const":"booking.surface.v2"},"kind":{"$ref":"#/$defs/Kind"},"actionId":{"$ref":"#/$defs/Ref"},"contextRef":{"$ref":"#/$defs/Ref"},"expectedRevision":{"type":"integer","minimum":0},"reason":{"type":"string","minLength":1,"maxLength":1000},"factRefs":{"type":"array","maxItems":64,"uniqueItems":true,"items":{"$ref":"#/$defs/Ref"}},"input":{"type":"object"},"relaxationApprovalRef":{"$ref":"#/$defs/ApprovalRef"}}},
+    "Action":{"oneOf":[
+      {"allOf":[{"$ref":"#/$defs/ActionBase"},{"type":"object","properties":{"kind":{"const":"search.patch"},"input":{"$ref":"https://gotry.dev/schemas/booking.surface.v1.schema.json#/$defs/SearchPatchInputV1"}}}]},
+      {"allOf":[{"$ref":"#/$defs/ActionBase"},{"type":"object","properties":{"kind":{"const":"search.run"},"input":{"$ref":"https://gotry.dev/schemas/booking.surface.v1.schema.json#/$defs/SearchRunInputV1"}}}]},
+      {"allOf":[{"$ref":"#/$defs/ActionBase"},{"type":"object","properties":{"kind":{"const":"results.view.patch"},"input":{"$ref":"https://gotry.dev/schemas/booking.surface.v1.schema.json#/$defs/ResultsViewPatchInputV1"}}}]},
+      {"allOf":[{"$ref":"#/$defs/ActionBase"},{"type":"object","properties":{"kind":{"const":"hotel.focus"},"input":{"$ref":"https://gotry.dev/schemas/booking.surface.v1.schema.json#/$defs/HotelFocusInputV1"}}}]},
+      {"allOf":[{"$ref":"#/$defs/ActionBase"},{"type":"object","properties":{"kind":{"const":"hotel.select"},"input":{"$ref":"https://gotry.dev/schemas/booking.surface.v1.schema.json#/$defs/HotelSelectInputV1"}}}]},
+      {"allOf":[{"$ref":"#/$defs/ActionBase"},{"type":"object","properties":{"kind":{"const":"offers.query"},"input":{"$ref":"https://gotry.dev/schemas/booking.surface.v1.schema.json#/$defs/OffersQueryInputV1"}}}]},
+      {"allOf":[{"$ref":"#/$defs/ActionBase"},{"type":"object","properties":{"kind":{"const":"offers.view.patch"},"input":{"$ref":"https://gotry.dev/schemas/booking.surface.v1.schema.json#/$defs/OffersViewPatchInputV1"}}}]},
+      {"allOf":[{"$ref":"#/$defs/ActionBase"},{"type":"object","properties":{"kind":{"const":"offers.compare"},"input":{"$ref":"https://gotry.dev/schemas/booking.surface.v1.schema.json#/$defs/OffersCompareInputV1"}}}]},
+      {"allOf":[{"$ref":"#/$defs/ActionBase"},{"type":"object","properties":{"kind":{"const":"offer.select"},"input":{"$ref":"#/$defs/OfferVersionInput"}}}]},
+      {"allOf":[{"$ref":"#/$defs/ActionBase"},{"type":"object","properties":{"kind":{"const":"offer.check"},"input":{"$ref":"#/$defs/OfferVersionInput"}}}]},
+      {"allOf":[{"$ref":"#/$defs/ActionBase"},{"type":"object","properties":{"kind":{"const":"checkout.prepare"},"input":{"$ref":"#/$defs/CheckoutPrepareVersionInput"}}}]},
+      {"allOf":[{"$ref":"#/$defs/ActionBase"},{"type":"object","properties":{"kind":{"const":"order.observe"},"input":{"$ref":"https://gotry.dev/schemas/booking.surface.v1.schema.json#/$defs/OrderObserveInputV1"}}}]}
+    ]},
+    "Approval":{"type":"object","additionalProperties":false,"required":["taskId","contextRef","sourceTurnId","presentationRequestKey","optionDigest","approvalId","deliveryNonce","blockerId","sourceActionId","sourceReceiptDigest","scope","code","criterionPath","valueDigest","from","to","approved"],"properties":{"taskId":{"$ref":"#/$defs/Ref"},"contextRef":{"$ref":"#/$defs/Ref"},"sourceTurnId":{"$ref":"#/$defs/Ref"},"presentationRequestKey":{"$ref":"#/$defs/PresentationKey"},"optionDigest":{"$ref":"#/$defs/Hex64"},"approvalId":{"$ref":"#/$defs/Ref"},"deliveryNonce":{"$ref":"#/$defs/Ref"},"blockerId":{"$ref":"#/$defs/Ref"},"sourceActionId":{"$ref":"#/$defs/Ref"},"sourceReceiptDigest":{"$ref":"#/$defs/Hex64"},"scope":{"enum":["search","offer","availability","checkout"]},"code":{"enum":["no_hotels_matched","hotel_not_visible","hotel_rates_failed","criterion_must_not_met","offer_target_not_reached","offer_unavailable"]},"criterionPath":{"type":"string","pattern":"^(searchDraft|results|offers|checkout)(\\.[A-Za-z][A-Za-z0-9_]*){0,3}$","maxLength":160},"valueDigest":{"$ref":"#/$defs/Hex64"},"from":{"const":"must"},"to":{"enum":["prefer","drop"]},"approved":{"const":true}}},
+    "Blocker":{"type":"object","additionalProperties":false,"required":["blockerId","sourceActionId","sourceReceiptDigest","scope","code","criterionPath","strength","valueDigest","evidence"],"properties":{"blockerId":{"$ref":"#/$defs/Ref"},"sourceActionId":{"$ref":"#/$defs/Ref"},"sourceReceiptDigest":{"$ref":"#/$defs/Hex64"},"scope":{"enum":["search","offer","availability","checkout"]},"code":{"enum":["no_hotels_matched","hotel_not_visible","hotel_rates_failed","criterion_must_not_met","offer_target_not_reached","offer_unavailable"]},"criterionPath":{"type":"string","pattern":"^(searchDraft|results|offers|checkout)(\\.[A-Za-z][A-Za-z0-9_]*){0,3}$","maxLength":160},"strength":{"const":"must"},"valueDigest":{"$ref":"#/$defs/Hex64"},"valueLabel":{"type":"string","minLength":1,"maxLength":120},"evidence":{"type":"object","additionalProperties":false,"required":["factRefs","gapCodes"],"properties":{"factRefs":{"type":"array","minItems":1,"maxItems":32,"uniqueItems":true,"items":{"$ref":"#/$defs/Ref"}},"gapCodes":{"$ref":"#/$defs/Codes"},"requested":{"type":"integer","minimum":0},"actual":{"type":"integer","minimum":0}}}}},
+    "Result":{"type":"object","additionalProperties":false,"required":["outcome","hardCriteriaMet","factRefs","gapCodes","blockers","relaxationsApplied"],"properties":{"outcome":{"enum":["complete","partial","empty"]},"requestedCount":{"type":"integer","minimum":0},"actualCount":{"type":"integer","minimum":0},"hardCriteriaMet":{"type":"boolean"},"factRefs":{"type":"array","maxItems":64,"uniqueItems":true,"items":{"$ref":"#/$defs/Ref"}},"gapCodes":{"$ref":"#/$defs/Codes"},"blockers":{"type":"array","maxItems":8,"items":{"$ref":"#/$defs/Blocker"}},"relaxationsApplied":{"type":"array","maxItems":1,"items":{"$ref":"#/$defs/Approval"}}}},
+    "Observation":{"oneOf":[{"type":"object","additionalProperties":false,"required":["kind"],"properties":{"kind":{"const":"search.state"},"searchSessionRef":{"$ref":"#/$defs/Ref"},"resultCount":{"type":"integer","minimum":0},"gapCodes":{"$ref":"#/$defs/Codes"}}},{"type":"object","additionalProperties":false,"required":["kind","matchedHotelRefs","visibleCount"],"properties":{"kind":{"const":"results.state"},"matchedHotelRefs":{"type":"array","maxItems":100,"items":{"$ref":"#/$defs/Ref"}},"visibleCount":{"type":"integer","minimum":0},"gapCodes":{"$ref":"#/$defs/Codes"}}},{"type":"object","additionalProperties":false,"required":["kind","hotelRef"],"properties":{"kind":{"enum":["hotel.focus","hotel.selection"]},"hotelRef":{"$ref":"#/$defs/Ref"}}},{"type":"object","additionalProperties":false,"required":["kind","hotelRefs","offerRefs","loadedHotelCount"],"properties":{"kind":{"const":"offers.state"},"hotelRefs":{"type":"array","maxItems":100,"items":{"$ref":"#/$defs/Ref"}},"offerRefs":{"type":"array","maxItems":200,"items":{"$ref":"#/$defs/Ref"}},"loadedHotelCount":{"type":"integer","minimum":0},"gapCodes":{"$ref":"#/$defs/Codes"}}},{"type":"object","additionalProperties":false,"required":["kind","offerRef","checkedOfferVersionRef","available","changedFactRefs"],"properties":{"kind":{"const":"offer.availability"},"offerRef":{"$ref":"#/$defs/Ref"},"checkedOfferVersionRef":{"$ref":"#/$defs/Ref"},"currentOfferVersionRef":{"$ref":"#/$defs/Ref"},"verifiedOfferRef":{"$ref":"#/$defs/Ref"},"available":{"type":"boolean"},"changedFactRefs":{"type":"array","maxItems":64,"items":{"$ref":"#/$defs/Ref"}},"gapCodes":{"$ref":"#/$defs/Codes"}}},{"type":"object","additionalProperties":false,"required":["kind","code","factRefs"],"properties":{"kind":{"const":"gap"},"code":{"enum":["byos_mapped_risk","check_avail_failed","check_avail_unverified","component_executor_unavailable","hotel_not_visible","hotel_rates_failed","offer_facts_changed","offer_not_loaded","offer_unavailable","order_not_found","order_outcome_not_observed","order_state_unknown","order_status_unavailable","requested_offers_not_loaded","search_failed","search_form_invalid","search_session_expired","search_terminal_timeout","stale_revision","surface_adapter_failed","undo_token_not_found","unhandled","unsupported","verified_offer_required","workspace_changed_during_action","criterion_must_not_met","no_hotels_matched","offer_target_not_reached"]},"factRefs":{"type":"array","maxItems":64,"items":{"$ref":"#/$defs/Ref"}}}}]},
+    "OfferSelectionObservation":{"type":"object","additionalProperties":false,"required":["kind","offerRef","offerVersionRef"],"properties":{"kind":{"const":"offer.selection"},"offerRef":{"$ref":"#/$defs/Ref"},"offerVersionRef":{"$ref":"#/$defs/Ref"}}},
+    "HandoffObservation":{"type":"object","additionalProperties":false,"required":["kind","offerRef","offerVersionRef","verifiedOfferRef","handoffRef"],"properties":{"kind":{"const":"checkout.handoff"},"offerRef":{"$ref":"#/$defs/Ref"},"offerVersionRef":{"$ref":"#/$defs/Ref"},"verifiedOfferRef":{"$ref":"#/$defs/Ref"},"handoffRef":{"$ref":"#/$defs/Ref"}}},
+    "OrderObservation":{"type":"object","additionalProperties":false,"required":["kind","orderRef","state"],"properties":{"kind":{"const":"order.state"},"orderRef":{"$ref":"#/$defs/Ref"},"state":{"enum":["pending","verified","failed","unknown"]},"gapCodes":{"$ref":"#/$defs/Codes"}}},
+    "ObservationExpanded":{"oneOf":[{"$ref":"#/$defs/Observation"},{"$ref":"#/$defs/OfferSelectionObservation"},{"$ref":"#/$defs/HandoffObservation"},{"$ref":"#/$defs/OrderObservation"}]},
+    "Receipt":{"type":"object","additionalProperties":false,"required":["schemaVersion","kind","actionId","contextRef","status","revision","observation","resultContract"],"properties":{"schemaVersion":{"const":"booking.surface.v2"},"kind":{"const":"action.receipt"},"actionId":{"$ref":"#/$defs/Ref"},"contextRef":{"$ref":"#/$defs/Ref"},"status":{"enum":["applied","needs_input","partial","no_match","unavailable","changed","stale","unsupported","failed"]},"revision":{"type":"integer","minimum":0},"observation":{"$ref":"#/$defs/ObservationExpanded"},"resultContract":{"$ref":"#/$defs/Result"},"undoToken":{"$ref":"#/$defs/Ref"}}},
+    "Ingress":{"type":"object","additionalProperties":false,"required":["schemaVersion","kind","requestKey","surfaceHint","workspace","request"],"properties":{"schemaVersion":{"const":"booking.surface.v2"},"kind":{"const":"user.turn.ingress"},"requestKey":{"$ref":"#/$defs/RequestKey"},"taskHandle":{"$ref":"#/$defs/Ref"},"surfaceHint":{"$ref":"#/$defs/Surface"},"workspace":{"$ref":"#/$defs/IngressWorkspace"},"request":{"type":"object","additionalProperties":false,"required":["text"],"properties":{"text":{"type":"string","minLength":1,"maxLength":4000}}}}},
+    "UserTurn":{"type":"object","additionalProperties":false,"required":["schemaVersion","kind","taskId","turnId","workspace","request"],"properties":{"schemaVersion":{"const":"booking.surface.v2"},"kind":{"const":"user.turn"},"taskId":{"$ref":"#/$defs/Ref"},"turnId":{"$ref":"#/$defs/Ref"},"workspace":{"$ref":"#/$defs/Workspace"},"request":{"type":"object","additionalProperties":false,"required":["text"],"properties":{"text":{"type":"string","minLength":1,"maxLength":4000},"approval":{"$ref":"#/$defs/Approval"}}}}},
+    "Continuation":{"type":"object","additionalProperties":false,"required":["schemaVersion","kind","taskId","workspace","receipt"],"properties":{"schemaVersion":{"const":"booking.surface.v2"},"kind":{"const":"action.receipt.continuation"},"taskId":{"$ref":"#/$defs/Ref"},"workspace":{"$ref":"#/$defs/Workspace"},"receipt":{"$ref":"#/$defs/Receipt"}}},
+    "Event":{"oneOf":[
+      {"$ref":"#/$defs/StatusEvent"},{"$ref":"#/$defs/QuestionEvent"},{"$ref":"#/$defs/OperationEvent"},{"$ref":"#/$defs/ExplanationEvent"},{"$ref":"#/$defs/TerminalEvent"},{"$ref":"#/$defs/ErrorEvent"}
+    ]},
+    "EventBase":{"type":"object","required":["schemaVersion","eventId","taskId","contextRef","sequence","emittedAt","kind"],"properties":{"schemaVersion":{"const":"booking.surface.v2"},"eventId":{"$ref":"#/$defs/Ref"},"taskId":{"$ref":"#/$defs/Ref"},"contextRef":{"$ref":"#/$defs/Ref"},"sequence":{"type":"integer","minimum":1},"emittedAt":{"type":"string","minLength":1},"kind":{"enum":["status","question","operation","explanation","terminal","error"]}}},
+    "StatusEvent":{"type":"object","allOf":[{"$ref":"#/$defs/EventBase"},{"type":"object","required":["kind","status"],"properties":{"kind":{"const":"status"},"status":{"enum":["submitted","working","waiting_receipt","input_required"]}}}],"unevaluatedProperties":false},
+    "QuestionEvent":{"type":"object","additionalProperties":false,"required":["schemaVersion","eventId","taskId","contextRef","sequence","emittedAt","kind","question"],"properties":{"schemaVersion":{"const":"booking.surface.v2"},"eventId":{"$ref":"#/$defs/Ref"},"taskId":{"$ref":"#/$defs/Ref"},"contextRef":{"$ref":"#/$defs/Ref"},"sequence":{"type":"integer","minimum":1},"emittedAt":{"type":"string","minLength":1},"kind":{"const":"question"},"question":{"type":"object","additionalProperties":false,"required":["questionId","prompt","missingFields","type","blocker","approvalOptions"],"properties":{"questionId":{"$ref":"#/$defs/Ref"},"prompt":{"type":"string","minLength":1},"missingFields":{"type":"array","maxItems":32,"items":{"type":"string"}},"type":{"const":"relaxation_approval_required"},"blocker":{"$ref":"#/$defs/Blocker"},"approvalOptions":{"type":"array","minItems":1,"maxItems":2,"items":{"type":"object","additionalProperties":false,"required":["approval"],"properties":{"approval":{"$ref":"#/$defs/Approval"}}}}}}}},
+    "OperationEvent":{"type":"object","allOf":[{"$ref":"#/$defs/EventBase"},{"type":"object","required":["kind","action"],"properties":{"kind":{"const":"operation"},"action":{"$ref":"#/$defs/Action"}}}],"unevaluatedProperties":false},
+    "ExplanationEvent":{"type":"object","allOf":[{"$ref":"#/$defs/EventBase"},{"type":"object","required":["kind","explanation"],"properties":{"kind":{"const":"explanation"},"explanation":{"type":"object","additionalProperties":false,"required":["text","factRefs"],"properties":{"text":{"type":"string","minLength":1},"factRefs":{"type":"array","maxItems":64,"items":{"$ref":"#/$defs/Ref"}}}}}}],"unevaluatedProperties":false},
+    "TerminalEvent":{"type":"object","allOf":[{"$ref":"#/$defs/EventBase"},{"type":"object","required":["kind","terminal"],"properties":{"kind":{"const":"terminal"},"terminal":{"type":"object","additionalProperties":false,"required":["status","summary","factRefs"],"properties":{"status":{"enum":["completed","stopped"]},"summary":{"type":"string","minLength":1},"factRefs":{"type":"array","maxItems":64,"items":{"$ref":"#/$defs/Ref"}}}}}}],"unevaluatedProperties":false},
+    "ErrorEvent":{"type":"object","allOf":[{"$ref":"#/$defs/EventBase"},{"type":"object","required":["kind","error"],"properties":{"kind":{"const":"error"},"error":{"type":"object","additionalProperties":false,"required":["code","message","retryable"],"properties":{"code":{"type":"string","pattern":"^[A-Z][A-Z0-9_.-]*$"},"message":{"type":"string","minLength":1},"retryable":{"type":"boolean"}}}}}],"unevaluatedProperties":false}
+  }
+}

package/ts/capabilities/flyai.ts

@@ -15,6 +15,9 @@
  */
 
 import { spawn } from 'node:child_process'
+import { closeSync, openSync, readFileSync, unlinkSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
 
 export type FlyaiKind = 'flight' | 'train' | 'hotel'
 
@@ -175,20 +178,30 @@ export function parseFlyaiItemList(stdout: string): unknown[] {
 }
 
 
+/**
+ * 子进程 stdout 走临时文件而非管道(issue #84):
+ * flyai CLI 异步写 stdout 后立即 process.exit();stdout 是管道时未 flush 的
+ * 尾部会被丢掉(实测截断在 ~7.6KB,exit=0 静默)。stdout 是文件时 Node 同步写,
+ * exit 不丢数据;且文件无 64KB 管道缓冲上限。close 后读文件,语义不变。
+ */
 function sh(cmd: string, args: string[], opts: { timeoutMs: number }) {
-  const child = spawn(cmd, args, { env: process.env, cwd: process.cwd() })
-  let stdout = ''
+  const outFile = join(tmpdir(), `gotry-flyai-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.out`)
+  const outFd = openSync(outFile, 'w')
+  const child = spawn(cmd, args, { env: process.env, cwd: process.cwd(), stdio: ['ignore', outFd, 'pipe'] })
   let stderr = ''
   let error: string | undefined
   const timer = setTimeout(() => {
     try { child.kill('SIGKILL') } catch { /* ignore */ }
   }, opts.timeoutMs)
   return new Promise<{ code: number; stdout: string; stderr: string; error?: string; timedOut?: boolean }>((resolve) => {
-    child.stdout?.on('data', (d: Buffer) => { stdout += d.toString() })
     child.stderr?.on('data', (d: Buffer) => { stderr += d.toString() })
     child.on('error', (e) => { error = (e as Error).message.slice(0, 200) })
     child.on('close', (code) => {
       clearTimeout(timer)
+      closeSync(outFd)
+      let stdout = ''
+      try { stdout = readFileSync(outFile, 'utf8') } catch { /* 子进程未启动时文件可能为空,按空 stdout 处理 */ }
+      try { unlinkSync(outFile) } catch { /* ignore */ }
       resolve({ code: code ?? -1, stdout, stderr, error })
     })
   }).finally(() => clearTimeout(timer))

package/ts/capabilities/session/extension-bridge.ts

@@ -5,14 +5,16 @@
  * host_permissions 一一对应,防漂移测试守住);**零新依赖**(node:http 手写,对齐已退役 shell 薄壳
  * 的回环纪律;不引 ws——MV3 Service Worker 靠 ≤20s 的长轮询节奏维持 30s 存活窗口,HTTP 够用)。
  *
- * 授权模型:扩展经「一次性安装 + manifest 固定 key(扩展 ID 跨机器稳定)」获得信任,
- * 每请求校验 Origin === chrome-extension://<固定ID>(网页发起的跨域请求必带邪恶 Origin,直接 403;
- * POST 端点强制;GET /health /status 是本机诊断面放行)。不做 CORS——有 host_permissions 的扩展
- * fetch 天然免预检,网页过不来。
+ * 授权模型:扩展经「一次性安装」获得信任,每请求校验 Origin ∈ 双通道扩展源白名单
+ * (网页发起的跨域请求必带邪恶 Origin,直接 403;POST 端点强制;GET /health /status 是本机
+ * 诊断面放行)。不做 CORS——有 host_permissions 的扩展 fetch 天然免预检,网页过不来。
+ * 双通道 ID 实录(2026-09-02):unpacked 通道(bundled/GitHub Releases)由 manifest 固定 key
+ * 派生 EXTENSION_ID;Chrome Web Store 用商店自己的签名 key 重签(不认 manifest key),
+ * 商店版 ID = EXTENSION_ID_STORE。两个 ID 都是 founder 控制的同一扩展,白名单双收。
  *
  * 协议(长轮询):
  *   GET  /health           → lastSeen 刷新(扩展每 ≤30s 一次 + 每次断线重连)
- *   GET  /status           → 诊断面 {port, extensionConnected, lastSeenMsAgo}
+ *   GET  /status           → 诊断面 {port, extensionConnected, lastSeenMsAgo, queued, inFlight, parked}
  *   POST /jobs             → 长轮询取活(hold ≤20s 返 {job:null});扩展单客户端
  *   POST /results/:jobId   → 善果/失败回传(≤8MB;batchSearch ~550KB)
  * 语义:桥不存在即整个扩展车道不存在——fail-closed 不变量在调用方(session-search 的 needs-extension)。
@@ -25,9 +27,20 @@ import { createServer, type IncomingMessage, type Server, type ServerResponse }
 /** 桥端口池(extension/manifest.json host_permissions 必须同面;§38 断言) */
 export const BRIDGE_PORTS = [8791, 8792, 8793, 8794, 8795] as const
 export const BRIDGE_PROTOCOL = 'session-bridge.v1'
-/** 扩展固定 ID(manifest key 派生;变更即失配,Node 侧拒绝) */
+/** 扩展固定 ID(unpacked 通道:manifest key 派生;bundled/GitHub Releases 均此 ID。变更即失配,Node 侧拒绝) */
 export const EXTENSION_ID = 'olpgkofjhhiiiahdkkbcninhjmegghfe'
 export const EXTENSION_ORIGIN = `chrome-extension://${EXTENSION_ID}`
+/**
+ * Chrome Web Store 版扩展 ID(2026-09-02 上架):商店用自己生成的签名 key 重签,
+ * **不认 manifest 里的固定 key**——商店版 ID 与 unpacked 版不同(上架材料文档的
+ * 「若商店不认 key」预案坐实)。item ID 即商店详情页 URL 末段。
+ */
+export const EXTENSION_ID_STORE = 'oeajpiccmonococjcegddlooeeohlbgd'
+export const EXTENSION_ORIGIN_STORE = `chrome-extension://${EXTENSION_ID_STORE}`
+/** 商店详情页(一键安装 + 自动更新通道;推荐安装方式) */
+export const EXTENSION_STORE_URL = `https://chromewebstore.google.com/detail/gotry-session-bridge/${EXTENSION_ID_STORE}`
+/** 桥信任的扩展 Origin 白名单:unpacked(固定 key)+ 商店版,双通道同一扩展同源信任 */
+export const EXTENSION_ORIGINS: readonly string[] = [EXTENSION_ORIGIN, EXTENSION_ORIGIN_STORE]
 /** 扩展在线判定:/health 心跳 ≤30s 一次 + 轮询重连,1.5 倍容差 */
 export const EXTENSION_CONNECTED_WINDOW_MS = 45_000
 /** /jobs 长轮询 hold 上限(必须 < MV3 SW 30s 存活窗口) */
@@ -76,7 +89,8 @@ export interface SessionJobHandle {
 export interface SessionBridgeOptions {
   /** 测试用 [0] 让 OS 分配;缺省 8791..8795 端口池 */
   ports?: number[]
-  extensionOrigin?: string
+  /** 测试覆盖信任的扩展 Origin 白名单;缺省 EXTENSION_ORIGINS(unpacked + 商店版双通道) */
+  extensionOrigins?: readonly string[]
   now?: () => number
   /**
    * **保持桥进程钉住事件循环**(不 unref)。wizard 期间需要:扩展 SW 周期心跳
@@ -118,7 +132,7 @@ function readBody(req: IncomingMessage, cap: number): Promise<string | { err: st
 /** 创 Bridge 服务(测试可直接调;生产走 getOrCreateSessionBridge 懒单例) */
 export async function createSessionBridge(opts: SessionBridgeOptions = {}): Promise<{ ok: true; bridge: SessionJobHandle } | { ok: false; summary: string }> {
   const ports = opts.ports ?? [...BRIDGE_PORTS]
-  const extensionOrigin = opts.extensionOrigin ?? EXTENSION_ORIGIN
+  const extensionOrigins = new Set(opts.extensionOrigins ?? EXTENSION_ORIGINS)
   const now = opts.now ?? Date.now
   const queue: QueuedJob[] = []
   const inFlight = new Map<string, QueuedJob>()
@@ -140,17 +154,18 @@ export async function createSessionBridge(opts: SessionBridgeOptions = {}): Prom
     const urlPath = (req.url ?? '').split('?')[0]
     const origin = req.headers.origin
     const isPost = req.method === 'POST'
-    // 网页侧请求必带 Origin;桥端点只信任本扩展的 chrome-extension:// 源(诊断 GET 面放行)
-    if (isPost && origin !== extensionOrigin) {
+    const originTrusted = typeof origin === 'string' && extensionOrigins.has(origin)
+    // 网页侧请求必带 Origin;桥端点只信任白名单内的 chrome-extension:// 源(诊断 GET 面放行)
+    if (isPost && !originTrusted) {
       res.statusCode = 403
       res.setHeader('content-type', 'application/json')
       res.end(JSON.stringify({ ok: false, error: 'origin 不在桥白名单' }))
       return
     }
     // 心跳:扩展平时只走 /jobs 长轮询(健康只在启动探测时 ping 一次)——
-    // 一切携带本扩展 Origin 的请求都刷新 lastSeen,否则 45s 后误判扩展掉线;
+    // 一切携带白名单扩展 Origin 的请求都刷新 lastSeen,否则 45s 后误判扩展掉线;
     // 无 Origin 的诊断 GET(/health /status)不记心跳,curl 探活不能伪造「扩展在线」
-    if (origin === extensionOrigin) {
+    if (originTrusted) {
       lastSeenAt = now()
     }
     const finish = (code: number, body: unknown): void => {
@@ -169,6 +184,7 @@ export async function createSessionBridge(opts: SessionBridgeOptions = {}): Prom
         lastSeenMsAgo: lastSeenAt > 0 ? now() - lastSeenAt : null,
         queued: queue.length,
         inFlight: inFlight.size,
+        parked: parked.length,
       })
       return
     }
@@ -182,6 +198,9 @@ export async function createSessionBridge(opts: SessionBridgeOptions = {}): Prom
         if (i >= 0) parked.splice(i, 1)
         finish(200, { job: null })
       }, JOBS_LONG_POLL_MS)
+      // 默认桥是惰性能力:外部扩展的 parked 轮询不得在主流程结束后钉住 CLI。
+      // keepBridge wizard 反过来要靠它守住进程,因此只对默认形态 unref。
+      if (!opts.keepBridge) parkTimer.unref()
       parked.push({ res, timer: parkTimer })
       res.on('close', () => {
         const i = parked.findIndex((p) => p.res === res)
@@ -208,6 +227,10 @@ export async function createSessionBridge(opts: SessionBridgeOptions = {}): Prom
     }
     finish(404, { ok: false, error: 'unknown endpoint' })
   })
+  server.on('connection', (socket) => {
+    // server.unref() 只解开监听器;已接受的扩展长轮询 socket 仍会引用事件循环。
+    if (!opts.keepBridge) socket.unref()
+  })
 
   /** 扩展回包:queued 与 inFlight 两处都可寻址(job 执行失败 = result.ok:false,桥自身不吞) */
   function resolveJob(jobId: string, parsed: ExtensionJobResult): void {
@@ -269,7 +292,7 @@ export async function createSessionBridge(opts: SessionBridgeOptions = {}): Prom
             settle({
               ok: false,
               reason: 'extension-not-connected',
-              summary: 'GoTry Session Bridge 扩展未连接(未安装或已停用)。一次性安装:npx gotry setup 查看指引 → chrome://extensions 开发者模式「加载已解压的扩展程序」指向 ~/.gotry/extension',
+              summary: `GoTry Session Bridge 扩展未连接(未安装或已停用)。一次性安装(装完零弹窗):推荐 Chrome 应用商店一键装(自动更新) ${EXTENSION_STORE_URL} ;或 npx gotry setup 落位后 chrome://extensions 开发者模式「加载已解压的扩展程序」指向 ~/.gotry/extension`,
             })
           }
         }, 250)
@@ -351,4 +374,4 @@ export async function __resetSessionBridgeForTest(): Promise<void> {
 /** 测试注入:以临时端口的桥替换单例(channel 层测试不碰真实端口池) */
 export function __setSessionBridgeForTest(bridge: SessionJobHandle | null): void {
   singleton = bridge ? { ok: true, bridge } : null
-}
+}

package/ts/capabilities/session/extension-channel.ts

@@ -10,12 +10,15 @@
  * 检索页无回包不是车道失败:与 CDP 车道同语义(到点无 hints 命中 ⇒ miss,页标题命挑战 ⇒ challenged)。
  */
 
-import { getOrCreateSessionBridge, type SessionJobHandle } from './extension-bridge.ts'
+import { getOrCreateSessionBridge, EXTENSION_STORE_URL, type SessionJobHandle } from './extension-bridge.ts'
 
 /** 一次性用户门文案(needs-extension 统一指引,与 bootstrap setupExtension 输出同口径) */
 export const NEEDS_EXTENSION_HINT =
-  '需要一次性安装 GoTry Session Bridge 浏览器扩展(约 30 秒,装完零弹窗):跑 npx gotry setup 拿指引,'
-  + '或在 chrome://extensions 开发者模式「加载已解压的扩展程序」指向 ~/.gotry/extension'
+  '需要一次性安装 GoTry Session Bridge 浏览器扩展(装完零弹窗):'
+  + `推荐 Chrome 应用商店一键安装(自动更新) ${EXTENSION_STORE_URL} ;`
+  + '免审核、版本更新更快的 GitHub 通道:npx gotry setup --extension-from=github(自动下载落位 ~/.gotry/extension;'
+  + '手动下载 github.com/Danceiny/gotry/releases 标签 ext-* 的 gotry-session-bridge.tar.gz),'
+  + '再在 chrome://extensions 开发者模式「加载已解压的扩展程序」指向解压目录'
 
 export type BridgeFailureKind = 'bridge-unavailable' | 'extension-not-connected' | 'timeout' | 'job-error'
 

package/ts/capabilities/session/extension-distribution.ts

@@ -0,0 +1,264 @@
+/**
+ * 扩展产物分发(issue #21 分发通道,ADR-21;founder 2026-08-30「产物下载和安装也得做成更好的
+ * 用户体验,可以用 github 作为分发渠道」)。
+ *
+ * 平台硬约束(诚实前置):Chrome 禁止普通用户从任意 URL 安装打包 CRX——GitHub 只能改善
+ * 「下载」(版本化/回滚/与 npm 发版节奏解耦),改善不了「安装」;「开发者模式加载已解压」
+ * 那 3 次点击只有上架 Chrome Web Store 才能消掉(商店版自动更新,见 extension-webstore-submission.md)。
+ * manifest 固定 key ⇒ 双通道是同一个扩展 ID(olpgkofjhhiiiahdkkbcninhjmegghfe),端口池/
+ * host_permissions 不随通道漂移——本模块用 key 钉住这一不变量。
+ *
+ * 单一职责:① 产物源解析(bundled 默认离线确定性 | github 显式 opt-in);
+ * ② GitHub Releases 下载链:dist-manifest → tar.gz → SHA256 校验 → tar 解压 → key 钉扎校验
+ *    → 版本比较 → 原子交换 ~/.gotry/extension;
+ * ③ 失败语义:github 源任何失败(无网/404/校验不过/key 漂移)→ 结构化 fallback bundled,
+ *    绝不挡 setup(安装外部产物永远不挡 gotry 本体——bootstrap 契约)。
+ *
+ * 信任边界(诚实声明):TLS 传输 + 同源 dist-manifest 哈希完整性——防截断/损坏/误传资产,
+ * 不防仓库本身被攻陷(无独立 pinning;独立 pin 需把哈希烘进 npm 包,与「扩展更新与 npm
+ * 发版解耦」目标冲突,明确不做)。
+ *
+ * 零新 npm 依赖:fetch 走 Node ≥22 全局;解压走平台原生 `tar -xzf`(macOS/Linux/Windows10+
+ * 自带);SHA256 走 node:crypto。spawn/fetch 可注入(离线测试)。
+ */
+
+import { spawn } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** Releases 稳定资产名(每版覆盖同名上传;latest/download 永久链只认稳定名)。
+ *  与 scripts/package-extension.mjs 的资产名必须逐字一致——extension-distribution-tests 防漂移。 */
+export const DIST_ASSET_TARBALL = 'gotry-session-bridge.tar.gz'
+export const DIST_ASSET_STORE_ZIP = 'gotry-session-bridge-store.zip'
+export const DIST_ASSET_MANIFEST = 'extension-dist-manifest.json'
+
+export const DEFAULT_RELEASE_BASE = 'https://github.com/Danceiny/gotry/releases'
+
+export interface ExtensionDistManifest {
+  version: string
+  tarball: string
+  tarballSha256: string
+  zip: string
+  zipSha256: string
+  builtFromCommit?: string
+}
+
+export interface GithubSourceOptions {
+  /** Releases 基址(测试/镜像可指回环);默认 GitHub 官方 */
+  releaseBase?: string
+  /** 注入 fetch(离线测试);默认全局 fetch */
+  fetch?: typeof fetch
+  /** 注入 spawn(离线测试拦截 tar);默认 child_process.spawn */
+  spawnFn?: typeof spawn
+  /** 下载/解压超时(默认 60s,有界) */
+  timeoutMs?: number
+}
+
+export type ExtensionInstallAction = 'installed' | 'up-to-date' | 'fallback-bundled'
+
+export interface ExtensionInstallResult {
+  ok: boolean
+  action: ExtensionInstallAction
+  /** 远端 dist-manifest 声明的版本(action=up-to-date 时也带回,供比较报告) */
+  version?: string
+  /** 交换前 dest 里已就位的版本(无则 undefined) */
+  previousVersion?: string
+  error?: string
+}
+
+/** 纯函数:三段数字版本比较(a<b 负 / 相等 0 / a>b 正;非数字段按 0 处理,长度差补 0) */
+export function compareVersions(a: string, b: string): number {
+  const pa = String(a).split('.').map((s) => Number.parseInt(s, 10) || 0)
+  const pb = String(b).split('.').map((s) => Number.parseInt(s, 10) || 0)
+  const n = Math.max(pa.length, pb.length)
+  for (let i = 0; i < n; i += 1) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0)
+    if (d !== 0) return d
+  }
+  return 0
+}
+
+/** 纯函数:Releases latest/download 永久链(稳定资产名) */
+export function distAssetUrls(releaseBase: string = DEFAULT_RELEASE_BASE): { tarball: string; storeZip: string; manifest: string } {
+  const base = releaseBase.replace(/\/+$/, '')
+  return {
+    tarball: `${base}/latest/download/${DIST_ASSET_TARBALL}`,
+    storeZip: `${base}/latest/download/${DIST_ASSET_STORE_ZIP}`,
+    manifest: `${base}/latest/download/${DIST_ASSET_MANIFEST}`,
+  }
+}
+
+const SHA256_RE = /^[0-9a-f]{64}$/
+
+/** 纯函数:dist-manifest 解析,fail-closed(坏 JSON/缺字段/资产名漂移/哈希非 64-hex 一律拒绝) */
+export function parseDistManifest(raw: string): ExtensionDistManifest {
+  let obj: Record<string, unknown>
+  try {
+    obj = JSON.parse(raw) as Record<string, unknown>
+  } catch {
+    throw new Error('dist-manifest 不是合法 JSON')
+  }
+  const version = obj.version
+  const tarball = obj.tarball
+  const tarballSha256 = obj.tarballSha256
+  const zip = obj.zip
+  const zipSha256 = obj.zipSha256
+  if (typeof version !== 'string' || !/^\d+\.\d+\.\d+$/.test(version)) throw new Error('dist-manifest.version 缺失或非 x.y.z')
+  if (tarball !== DIST_ASSET_TARBALL) throw new Error(`dist-manifest.tarball 资产名漂移(期望 ${DIST_ASSET_TARBALL})`)
+  if (zip !== DIST_ASSET_STORE_ZIP) throw new Error(`dist-manifest.zip 资产名漂移(期望 ${DIST_ASSET_STORE_ZIP})`)
+  if (typeof tarballSha256 !== 'string' || !SHA256_RE.test(tarballSha256)) throw new Error('dist-manifest.tarballSha256 非 64-hex')
+  if (typeof zipSha256 !== 'string' || !SHA256_RE.test(zipSha256)) throw new Error('dist-manifest.zipSha256 非 64-hex')
+  return {
+    version,
+    tarball,
+    tarballSha256,
+    zip,
+    zipSha256,
+    builtFromCommit: typeof obj.builtFromCommit === 'string' ? obj.builtFromCommit : undefined,
+  }
+}
+
+export function sha256Hex(bytes: Uint8Array | string): string {
+  return createHash('sha256').update(bytes).digest('hex')
+}
+
+/** 读取扩展 manifest 的 key(固定 key ⇒ 固定扩展 ID;分发通道 ID 不变量的锚点) */
+export function readExtensionKey(extensionDir: string): string | undefined {
+  const p = join(extensionDir, 'manifest.json')
+  if (!existsSync(p)) return undefined
+  try {
+    const m = JSON.parse(readFileSync(p, 'utf8')) as { key?: unknown }
+    return typeof m.key === 'string' ? m.key : undefined
+  } catch {
+    return undefined
+  }
+}
+
+export function readExtensionVersion(extensionDir: string): string | undefined {
+  const p = join(extensionDir, 'manifest.json')
+  if (!existsSync(p)) return undefined
+  try {
+    const m = JSON.parse(readFileSync(p, 'utf8')) as { version?: unknown }
+    return typeof m.version === 'string' ? m.version : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function runTar(args: string[], spawnFn: typeof spawn, timeoutMs: number): Promise<{ ok: boolean; error?: string }> {
+  return new Promise((resolve) => {
+    const child = spawnFn('tar', args, { stdio: 'ignore' })
+    let done = false
+    const timer = setTimeout(() => {
+      if (!done) {
+        done = true
+        try {
+          child.kill('SIGKILL')
+        } catch {
+          /* ignore */
+        }
+        resolve({ ok: false, error: `tar 超时(>${timeoutMs}ms)` })
+      }
+    }, timeoutMs)
+    child.on('error', (e) => {
+      if (!done) {
+        done = true
+        clearTimeout(timer)
+        resolve({ ok: false, error: `tar 不可用:${e.message}` })
+      }
+    })
+    child.on('close', (code) => {
+      if (!done) {
+        done = true
+        clearTimeout(timer)
+        resolve(code === 0 ? { ok: true } : { ok: false, error: `tar exit ${code}` })
+      }
+    })
+  })
+}
+
+async function fetchBytes(url: string, fetchFn: typeof fetch, timeoutMs: number): Promise<{ ok: true; bytes: Uint8Array } | { ok: false; error: string }> {
+  try {
+    const res = await fetchFn(url, { signal: AbortSignal.timeout(timeoutMs) })
+    if (!res.ok) return { ok: false, error: `HTTP ${res.status} ${url}` }
+    const buf = new Uint8Array(await res.arrayBuffer())
+    return { ok: true, bytes: buf }
+  } catch (e) {
+    return { ok: false, error: `下载失败 ${(e as Error).message}` }
+  }
+}
+
+export interface InstallFromGithubOptions extends GithubSourceOptions {
+  /** 落位目录(默认 ~/.gotry/extension 由调用方决定,本层不猜) */
+  destDir: string
+  /** 钉扎参照:bundled extension/ 目录(其 manifest key 是 ID 不变量的基准;缺省只做版本校验) */
+  pinnedSourceDir?: string
+  /** 只报告不落盘(up-to-date/将安装哪个版本;不下载 tarball 之外的任何东西) */
+  checkOnly?: boolean
+}
+
+/**
+ * GitHub Releases → ~/.gotry/extension 安装链。
+ * 任何失败都返回 { ok:false, action:'fallback-bundled' }——调用方显式降级 bundled,
+ * 本函数不抛出(bootstrap 契约:安装外部产物永远不挡 gotry 本体)。
+ */
+export async function installExtensionFromGithub(opts: InstallFromGithubOptions): Promise<ExtensionInstallResult> {
+  const timeoutMs = opts.timeoutMs ?? 60_000
+  const fetchFn = opts.fetch ?? fetch
+  const spawnFn = opts.spawnFn ?? spawn
+  const urls = distAssetUrls(opts.releaseBase)
+  const fail = (error: string): ExtensionInstallResult => ({ ok: false, action: 'fallback-bundled', error })
+
+  const mRes = await fetchBytes(urls.manifest, fetchFn, timeoutMs)
+  if (!mRes.ok) return fail(mRes.error)
+  let manifest: ExtensionDistManifest
+  try {
+    manifest = parseDistManifest(new TextDecoder().decode(mRes.bytes))
+  } catch (e) {
+    return fail(`dist-manifest 校验失败:${(e as Error).message}`)
+  }
+
+  const previousVersion = readExtensionVersion(opts.destDir)
+  if (previousVersion != null && compareVersions(manifest.version, previousVersion) <= 0) {
+    return { ok: true, action: 'up-to-date', version: manifest.version, previousVersion }
+  }
+  if (opts.checkOnly) {
+    return { ok: true, action: 'up-to-date', version: manifest.version, previousVersion } // check-only 语义:报告远端版本,不落盘
+  }
+
+  const tRes = await fetchBytes(urls.tarball, fetchFn, timeoutMs)
+  if (!tRes.ok) return fail(tRes.error)
+  const actual = sha256Hex(tRes.bytes)
+  if (actual !== manifest.tarballSha256) return fail(`SHA256 不符(期望 ${manifest.tarballSha256.slice(0, 12)}… 实得 ${actual.slice(0, 12)}…)`)
+
+  // 落盘 → tar 解压 → key 钉扎 → 原子交换;incoming 目录同盘保证 rename 原子性
+  const incoming = `${opts.destDir}.incoming-${process.pid}-${Date.now()}`
+  const tarPath = `${incoming}.tar.gz`
+  try {
+    rmSync(incoming, { recursive: true, force: true })
+    mkdirSync(incoming, { recursive: true })
+    writeFileSync(tarPath, tRes.bytes)
+    // 包内含顶层目录 gotry-session-bridge/;--strip-components 落到 incoming 根
+    const ext = await runTar(['-xzf', tarPath, '-C', incoming, '--strip-components', '1'], spawnFn, timeoutMs)
+    if (!ext.ok) return fail(ext.error!)
+
+    const incomingKey = readExtensionKey(incoming)
+    if (incomingKey == null) return fail('解压产物缺 manifest.json/key(非法包)')
+    if (opts.pinnedSourceDir) {
+      const pinnedKey = readExtensionKey(opts.pinnedSourceDir)
+      if (pinnedKey != null && incomingKey !== pinnedKey) return fail('扩展 key 漂移(通道产物与 bundled 不同 ID——拒绝安装,防端口池/host 权限漂移)')
+    }
+    const incomingVersion = readExtensionVersion(incoming)
+    if (incomingVersion !== manifest.version) return fail(`解压产物版本(${incomingVersion})与 dist-manifest(${manifest.version})不符`)
+
+    rmSync(opts.destDir, { recursive: true, force: true })
+    cpSync(incoming, opts.destDir, { recursive: true })
+    return { ok: true, action: 'installed', version: manifest.version, previousVersion }
+  } catch (e) {
+    return fail(`落位失败 ${(e as Error).message}`)
+  } finally {
+    rmSync(incoming, { recursive: true, force: true })
+    rmSync(tarPath, { force: true })
+  }
+}