Document universal local ASP agent connector architecture

Examples/agent-connector/README.md

@@ -0,0 +1,57 @@
+# Universal local agent connector (architecture sketch)
+
+This example applies Hypercode to the connector idea discussed on 2026-10-03.
+It is a **proposed architecture**, not a description of an existing app or an
+ASP conformance claim.
+
+The connector has one shared core for ASP discovery, origin checks, user
+consent, Grant coordination, local-agent mediation, result disclosure and
+revocation. Platform bindings supply the path from a requesting website to
+that core:
+
+- **iPhone:** an embedded browser and a native WebKit bridge.
+- **Mac:** an external browser and a loopback HTTP listener.
+
+Both paths terminate at the same origin-and-Grant gates. Website code proposes
+an action; it does not receive a Grant or credential and cannot add actions to
+the selected surface. The ASP authorization profile determines which authority
+issues a Grant; the connector coordinates acquisition and keeps any credential
+in connector-controlled custody. The remote application independently checks
+current authority when it executes the call.
+
+The `.hc` tree names responsibilities and platform components. Nesting does
+not assert runtime order. The two `.hcs` scenario traces therefore use explicit
+`sequence` and `next_step` properties. Hypercode validates their shape and
+contracts, but does not prove that an implementation follows those traces.
+
+The Mac loopback checks and iPhone bridge checks are design constraints that
+need platform-specific implementation evidence. In particular, binding to
+loopback does not itself authenticate a website; origin checks and a
+short-lived proof must gate action dispatch before side effects. Nor does this
+sketch establish that arbitrary desktop browsers permit a website-to-loopback
+HTTP request: browser security policy and transport behavior need a separate
+compatibility test before choosing this as the Mac binding.
+
+## Validate with the Hypercode compiler
+
+From the Hypercode repository root:
+
+```sh
+swift run hypercode validate Examples/agent-connector/connector.hc \
+  --hcs Examples/agent-connector/connector.hcs
+swift run hypercode validate Examples/agent-connector/connector.hc \
+  --hcs Examples/agent-connector/connector.hcs --ctx platform=ios
+swift run hypercode validate Examples/agent-connector/connector.hc \
+  --hcs Examples/agent-connector/connector.hcs --ctx platform=macos
+```
+
+Emit the resolved machine-readable representation with:
+
+```sh
+swift run hypercode emit Examples/agent-connector/connector.hc \
+  --hcs Examples/agent-connector/connector.hcs --format json
+```
+
+The `platform=ios` and `platform=macos` contexts resolve the connector's
+selected binding to different explicit values. They do not change the common
+Grant, consent, origin or result-disclosure constraints.

Examples/agent-connector/connector.hc

@@ -0,0 +1,36 @@
+ConnectorEcosystem#agent-connector-ecosystem
+  AgentConnector#local-agent-connector
+    SharedCore#shared-core
+      SurfaceClient#surface-client
+      OriginGate#origin-gate
+      ConsentBroker#consent-broker
+      GrantCoordinator#grant-coordinator
+      LocalAgentRuntime#agent-runtime
+      CapabilityDispatcher#dispatcher
+      ResultPresenter#result-presenter
+      RevocationController#revocation
+    PlatformBindings#platform-bindings
+      IOSConnector#ios-connector
+        EmbeddedBrowser#ios-browser
+        WebKitBridge#ios-bridge
+        NavigationGate#ios-navigation-gate
+      MacConnector#mac-connector
+        BrowserClient#mac-browser
+        LoopbackHTTPListener#mac-listener
+        LocalOriginGate#mac-origin-gate
+    Scenarios#scenarios
+      RequestFlow#ios-request
+        FlowStep.step#ios-01
+        FlowStep.step#ios-02
+        FlowStep.step#ios-03
+        FlowStep.step#ios-04
+        FlowStep.step#ios-05
+      RequestFlow#mac-request
+        FlowStep.step#mac-01
+        FlowStep.step#mac-02
+        FlowStep.step#mac-03
+        FlowStep.step#mac-04
+        FlowStep.step#mac-05
+  ASPApplication#remote-app
+    SurfaceManifest#remote-manifest
+    ActionExecutor#remote-executor

Examples/agent-connector/connector.hcs

@@ -0,0 +1,220 @@
+# Proposed architecture, not a deployed connector. The two platform bindings
+# share the ASP, Grant, consent, and local-agent core.
+
+AgentConnector:
+  lifecycle: "local application session"
+  authority_owner: "connector and user"
+  active_platform_binding: "unselected"
+
+@platform[ios]:
+  AgentConnector:
+    active_platform_binding: "ios-native-bridge"
+
+@platform[macos]:
+  AgentConnector:
+    active_platform_binding: "mac-loopback-http"
+
+'#surface-client':
+  discovery_source: "remote ASP application"
+  selects_actions: true
+
+'#origin-gate':
+  origin_required: true
+  origin_scope: "exact requesting site origin"
+  reject_opaque_origin: true
+
+'#consent-broker':
+  consent_required: true
+  consent_scope: "site origin, selected actions, disclosed data"
+  consent_lifetime: "bounded and revocable"
+
+'#grant-coordinator':
+  grant_issuer: "authorization authority selected by the ASP profile"
+  grant_custody: "connector-controlled secret store"
+  page_receives_grant: false
+  page_supplies_authority: false
+
+'#agent-runtime':
+  credential_source: "connector-controlled runtime"
+  receives_only_granted_actions: true
+  page_controls_runtime_configuration: false
+
+'#dispatcher':
+  checks_origin_and_grant_before_call: true
+  allows_undeclared_actions: false
+
+'#result-presenter':
+  returns_only_selected_result: true
+  discloses_receipt_or_credential: false
+
+'#revocation':
+  blocks_future_calls: true
+  recalls_previously_disclosed_data: false
+
+'#ios-connector':
+  transport: "in-app browser native bridge"
+
+'#ios-browser':
+  owns_web_content: true
+
+'#ios-bridge':
+  callable_by_page_without_consent: false
+  request_origin_checked_by_native_host: true
+  page_receives_grant: false
+
+'#ios-navigation-gate':
+  bridge_enabled_for_unapproved_origin: false
+  redirects_recheck_origin: true
+
+'#mac-connector':
+  transport: "candidate loopback HTTP binding; browser compatibility must be verified"
+
+'#mac-browser':
+  owns_web_content: false
+
+'#mac-listener':
+  bind_address: "127.0.0.1"
+  remote_network_access: false
+  browser_transport_compatibility_verified: false
+  check_origin_before_action: true
+  wildcard_origin_access: false
+  page_receives_bearer_credential: false
+
+'#mac-origin-gate':
+  reject_opaque_origin: true
+  require_short_lived_request_proof: true
+  proof_bound_to: "origin, action, session, expiry"
+
+'#remote-app':
+  enforces_grant_independently: true
+  verifies_current_session: true
+  publishes_curated_surface: true
+
+'#remote-manifest':
+  authority_source: "application-published ASP surface"
+
+'#remote-executor':
+  checks_current_grant_before_execution: true
+
+.step:
+  sequence: 1
+  participant: ""
+  operation: ""
+  gate: ""
+  next_step: "end"
+
+'#ios-01':
+  sequence: 1
+  participant: "website"
+  operation: "requests one declared action through the embedded browser"
+  gate: "none; request is only a proposal"
+  next_step: "ios-02"
+
+'#ios-02':
+  sequence: 2
+  participant: "native bridge"
+  operation: "binds the request to the visible page origin"
+  gate: "exact origin and navigation state"
+  next_step: "ios-03"
+
+'#ios-03':
+  sequence: 3
+  participant: "user and connector"
+  operation: "review the requested action and data disclosure"
+  gate: "explicit bounded consent"
+  next_step: "ios-04"
+
+'#ios-04':
+  sequence: 4
+  participant: "local agent runtime"
+  operation: "acts using only the selected Grant actions"
+  gate: "connector mediation and application enforcement"
+  next_step: "ios-05"
+
+'#ios-05':
+  sequence: 5
+  participant: "connector"
+  operation: "returns the permitted result to the requesting page"
+  gate: "result disclosure policy; no Grant or credential"
+  next_step: "end"
+
+'#mac-01':
+  sequence: 1
+  participant: "website"
+  operation: "requests one declared action from the local connector"
+  gate: "none; request is only a proposal"
+  next_step: "mac-02"
+
+'#mac-02':
+  sequence: 2
+  participant: "loopback listener"
+  operation: "accepts a request only on the loopback interface"
+  gate: "127.0.0.1 binding and bounded request"
+  next_step: "mac-03"
+
+'#mac-03':
+  sequence: 3
+  participant: "local origin gate"
+  operation: "checks origin and short-lived request proof"
+  gate: "origin, action, session, expiry"
+  next_step: "mac-04"
+
+'#mac-04':
+  sequence: 4
+  participant: "user and connector"
+  operation: "review consent, then mediate the selected action"
+  gate: "Grant and runtime policy"
+  next_step: "mac-05"
+
+'#mac-05':
+  sequence: 5
+  participant: "connector"
+  operation: "returns only the permitted result to the requesting page"
+  gate: "result disclosure policy; no Grant or credential"
+  next_step: "end"
+
+@contract:
+  AgentConnector:
+    lifecycle: string
+    authority_owner: string
+    active_platform_binding: string
+  SurfaceClient:
+    selects_actions: bool
+  OriginGate:
+    origin_required: bool
+    origin_scope: string
+    reject_opaque_origin: bool
+  ConsentBroker:
+    consent_required: bool
+    consent_scope: string
+    consent_lifetime: string
+  GrantCoordinator:
+    grant_issuer: string
+    grant_custody: string
+    page_receives_grant: bool
+    page_supplies_authority: bool
+  CapabilityDispatcher:
+    checks_origin_and_grant_before_call: bool
+    allows_undeclared_actions: bool
+  ResultPresenter:
+    returns_only_selected_result: bool
+    discloses_receipt_or_credential: bool
+  RevocationController:
+    blocks_future_calls: bool
+    recalls_previously_disclosed_data: bool
+  LoopbackHTTPListener:
+    bind_address: string
+    remote_network_access: bool
+    check_origin_before_action: bool
+    wildcard_origin_access: bool
+    page_receives_bearer_credential: bool
+  LocalOriginGate:
+    reject_opaque_origin: bool
+    require_short_lived_request_proof: bool
+    proof_bound_to: string
+  FlowStep:
+    sequence: int >= 1 <= 5
+    participant: string
+    operation: string
+    gate: string
+    next_step: string

README.md

@@ -120,7 +120,7 @@ hypercode resolve Examples/service.hc --hcs Examples/service.hcs --ctx env=produ
 | Path | What |
 |---|---|
 | `Sources/`, `Tests/`, `Package.swift` | Swift reference implementation (built on [SpecificationCore](https://github.com/SoundBlaster/SpecificationCore)) |
-| `Examples/` | Runnable `.hc` / `.hcs` (service, white-label) |
+| `Examples/` | Runnable `.hc` / `.hcs` (service, white-label, agent connector) |
 | `Schema/` | Versioned IR schema |
 | `RFC/`, `EBNF/*.md`, `DOCS/` | Specification & documents |
 | `EBNF/` (ANTLR / Java) | Conformance oracle for `.hc` parsing |