@botiverse/porthole 0.5.1 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +41 -0
- package/dist/bridge/bridge.d.ts +13 -0
- package/dist/bridge/bridge.js +208 -13
- package/dist/bridge/navigation.d.ts +1 -6
- package/dist/bridge/navigation.js +11 -0
- package/dist/bridge/refusal.d.ts +5 -1
- package/dist/bridge/refusal.js +16 -0
- package/dist/bridge/types.d.ts +41 -4
- package/dist/check/check.d.ts +19 -3
- package/dist/check/check.js +55 -8
- package/dist/check/files.d.ts +26 -0
- package/dist/check/files.js +307 -0
- package/dist/check/instrument.d.ts +3 -0
- package/dist/check/lint.js +31 -12
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.js +14 -0
- package/dist/check/tools.d.ts +23 -0
- package/dist/check/tools.js +27 -3
- package/dist/compile/policy.d.ts +34 -0
- package/dist/compile/policy.js +74 -0
- package/dist/config/capabilities.d.ts +62 -3
- package/dist/config/capabilities.js +20 -0
- package/dist/config/schema.d.ts +32 -0
- package/dist/config/validate.d.ts +1 -1
- package/dist/config/validate.js +74 -5
- package/dist/conformance/harness-source.js +1 -1
- package/dist/conformance/index.d.ts +1 -0
- package/dist/conformance/index.js +2 -0
- package/dist/conformance/runtime.d.ts +58 -0
- package/dist/conformance/runtime.js +314 -0
- package/dist/files/paths.d.ts +99 -0
- package/dist/files/paths.js +263 -0
- package/dist/files/types.d.ts +24 -0
- package/dist/files/types.js +83 -0
- package/dist/guide/gates.d.ts +3 -0
- package/dist/guide/gates.js +19 -0
- package/dist/guide/guide.d.ts +2 -0
- package/dist/guide/guide.js +44 -32
- package/dist/guide/limits.js +4 -4
- package/dist/guide/runtime.d.ts +13 -0
- package/dist/guide/runtime.js +202 -0
- package/dist/host/create-host.js +45 -0
- package/dist/host/locate.js +8 -0
- package/dist/host/locator.js +7 -0
- package/dist/host/types.d.ts +18 -0
- package/dist/index.d.ts +13 -4
- package/dist/index.js +16 -3
- package/dist/isolation/types.d.ts +8 -0
- package/dist/presets/presets.d.ts +6 -0
- package/dist/presets/presets.js +1 -0
- package/dist/protocol/adapter.d.ts +4 -0
- package/dist/protocol/mcp-apps.d.ts +6 -0
- package/dist/protocol/mcp-apps.js +6 -0
- package/dist/protocol/runtime-calls.d.ts +28 -0
- package/dist/protocol/runtime-calls.js +113 -0
- package/dist/protocol/shell-adapter.js +52 -3
- package/dist/react/dialog.js +31 -0
- package/dist/react/frame.d.ts +13 -0
- package/dist/react/frame.js +6 -0
- package/dist/runtime/contract.d.ts +193 -0
- package/dist/runtime/contract.js +216 -0
- package/dist/runtime/db.d.ts +153 -0
- package/dist/runtime/db.js +398 -0
- package/dist/runtime/declaration.d.ts +86 -0
- package/dist/runtime/declaration.js +266 -0
- package/dist/runtime/levels.d.ts +33 -0
- package/dist/runtime/levels.js +41 -0
- package/dist/runtime/requests.d.ts +125 -0
- package/dist/runtime/requests.js +199 -0
- package/dist/runtime/segments.d.ts +8 -0
- package/dist/runtime/segments.js +14 -0
- package/dist/runtime/types.generated.d.ts +1 -0
- package/dist/runtime/types.generated.js +19 -0
- package/dist/server/files.d.ts +57 -0
- package/dist/server/files.js +338 -0
- package/dist/server/host.d.ts +44 -2
- package/dist/server/host.js +42 -2
- package/dist/server/index.d.ts +5 -2
- package/dist/server/index.js +5 -1
- package/dist/server/keys.d.ts +8 -0
- package/dist/server/keys.js +34 -0
- package/dist/server/pseudonym.d.ts +9 -0
- package/dist/server/pseudonym.js +20 -0
- package/dist/server/server.d.ts +0 -5
- package/dist/server/server.js +468 -24
- package/dist/server/types.d.ts +118 -5
- package/dist/shell/document.d.ts +27 -0
- package/dist/shell/document.js +46 -2
- package/dist/shell/legacy.d.ts +21 -0
- package/dist/shell/legacy.js +63 -0
- package/dist/shell/plan.d.ts +17 -1
- package/dist/shell/plan.js +13 -2
- package/dist/shell/runtime.d.ts +2 -1
- package/dist/shell/runtime.js +114 -46
- package/dist/shell/use.d.ts +15 -0
- package/dist/shell/use.js +235 -0
- package/docs/ADOPTING.md +142 -5
- package/docs/ARCHITECTURE.md +34 -5
- package/docs/DECISIONS.md +716 -7
- package/docs/DESIGN.md +97 -3
- package/package.json +3 -1
- package/src/bridge/bridge.ts +281 -17
- package/src/bridge/navigation.ts +12 -0
- package/src/bridge/refusal.ts +16 -0
- package/src/bridge/types.ts +46 -4
- package/src/check/check.ts +100 -14
- package/src/check/files.ts +384 -0
- package/src/check/instrument.ts +3 -0
- package/src/check/lint.ts +33 -12
- package/src/check/page.ts +14 -0
- package/src/check/tools.ts +52 -3
- package/src/compile/policy.ts +92 -0
- package/src/config/capabilities.ts +49 -2
- package/src/config/schema.ts +32 -0
- package/src/config/validate.ts +107 -5
- package/src/conformance/index.ts +7 -0
- package/src/conformance/runtime.ts +573 -0
- package/src/files/paths.ts +323 -0
- package/src/files/types.ts +101 -0
- package/src/guide/gates.ts +25 -0
- package/src/guide/guide.ts +78 -52
- package/src/guide/limits.ts +4 -4
- package/src/guide/runtime.ts +244 -0
- package/src/host/create-host.ts +55 -0
- package/src/host/locate.ts +10 -0
- package/src/host/locator.ts +11 -0
- package/src/host/types.ts +18 -0
- package/src/index.ts +121 -0
- package/src/isolation/types.ts +8 -0
- package/src/presets/presets.ts +7 -0
- package/src/protocol/adapter.ts +3 -1
- package/src/protocol/mcp-apps.ts +7 -0
- package/src/protocol/runtime-calls.ts +138 -0
- package/src/protocol/shell-adapter.ts +56 -2
- package/src/react/dialog.tsx +33 -0
- package/src/react/frame.tsx +19 -0
- package/src/runtime/contract.ts +305 -0
- package/src/runtime/db.ts +530 -0
- package/src/runtime/declaration.ts +378 -0
- package/src/runtime/levels.ts +69 -0
- package/src/runtime/requests.ts +339 -0
- package/src/runtime/segments.ts +17 -0
- package/src/runtime/types.generated.ts +19 -0
- package/src/server/files.ts +425 -0
- package/src/server/host.ts +84 -3
- package/src/server/index.ts +22 -0
- package/src/server/keys.ts +53 -0
- package/src/server/pseudonym.ts +21 -0
- package/src/server/server.ts +565 -26
- package/src/server/types.ts +124 -4
- package/src/shell/document.ts +74 -4
- package/src/shell/legacy.ts +64 -0
- package/src/shell/plan.ts +37 -3
- package/src/shell/runtime.ts +114 -46
- package/src/shell/use.ts +235 -0
- package/types/runtime/v1/artifact.d.ts +50 -0
- package/types/runtime/v1/assets.d.ts +43 -0
- package/types/runtime/v1/chat.d.ts +13 -0
- package/types/runtime/v1/clipboard.d.ts +14 -0
- package/types/runtime/v1/comments.d.ts +24 -0
- package/types/runtime/v1/context.d.ts +16 -0
- package/types/runtime/v1/data.d.ts +29 -0
- package/types/runtime/v1/db.d.ts +110 -0
- package/types/runtime/v1/downloads.d.ts +22 -0
- package/types/runtime/v1/links.d.ts +13 -0
- package/types/runtime/v1/porthole.d.ts +44 -0
- package/types/runtime/v1/user.d.ts +19 -0
package/src/shell/runtime.ts
CHANGED
|
@@ -20,7 +20,8 @@
|
|
|
20
20
|
* 6. cancels every navigation the frame starts to another document (P079), before it sends a
|
|
21
21
|
* request: a navigation carries data out in its URL, and the embedding page's `frame-src`,
|
|
22
22
|
* the wall for that, must let served frames reach their own content origins. (Opaque frames
|
|
23
|
-
* get no navigate events: there `frame-src` is the wall.)
|
|
23
|
+
* get no navigate events: there `frame-src` is the wall.) A page that comes with files may
|
|
24
|
+
* open its set's other pages, under its version's own address, and nothing else (P084).
|
|
24
25
|
* A whole document (an artifact page, an MCP Apps view) is never written in: it is parsed inert,
|
|
25
26
|
* imported, and its scripts run in order, as a fragment's are.
|
|
26
27
|
*
|
|
@@ -35,6 +36,13 @@
|
|
|
35
36
|
export const SHELL_RUNTIME = String.raw`(() => {
|
|
36
37
|
"use strict";
|
|
37
38
|
const plan = __PLAN__;
|
|
39
|
+
// A page that came with files, answered at its ticket's address (P083): its own address first,
|
|
40
|
+
// before anything loads, so its relative addresses are its files' (and the ticket leaves).
|
|
41
|
+
if (plan.files && typeof plan.files.address === "string" && location.href !== plan.files.address) {
|
|
42
|
+
try {
|
|
43
|
+
history.replaceState(null, "", plan.files.address);
|
|
44
|
+
} catch (_) {}
|
|
45
|
+
}
|
|
38
46
|
// The embedding page's nonce, where it gave one (a srcdoc frame inherits its policy): every
|
|
39
47
|
// script the shell runs for the content carries it.
|
|
40
48
|
const nonce = document.currentScript && document.currentScript.nonce ? document.currentScript.nonce : "";
|
|
@@ -88,6 +96,31 @@ export const SHELL_RUNTIME = String.raw`(() => {
|
|
|
88
96
|
// frame) are none of this document's. Each one stopped is told to the host (P080), as an error
|
|
89
97
|
// report: below, once the shell can speak.
|
|
90
98
|
let navigationBlocked = (_url) => {};
|
|
99
|
+
// A page that comes with files (P084): another page of its own set, under the version's own
|
|
100
|
+
// address, is a page of the same content and opens in the frame (the host is told first, so it
|
|
101
|
+
// takes the next load for that page, not for content that left). Anything else stays stopped:
|
|
102
|
+
// another path of the origin, a file that isn't a page, another origin.
|
|
103
|
+
let navigating = (_url) => {};
|
|
104
|
+
let filesBase = plan.files && typeof plan.files.base === "string" ? plan.files.base : null;
|
|
105
|
+
// Every address the page's files had (P083: a sealed one is renewed): what reports say as "./".
|
|
106
|
+
const filesBases = filesBase === null ? [] : [filesBase];
|
|
107
|
+
// A frame's sealed files' address is its access: nothing the shell reports names it (P083).
|
|
108
|
+
const SEALED = /(?:https?:\/\/[^\s"'<>\/]+)?\/__porthole\/f\/[A-Za-z0-9_-]{20,}\//g;
|
|
109
|
+
const ownAddresses = (text) => {
|
|
110
|
+
let out = String(text);
|
|
111
|
+
for (const base of filesBases) {
|
|
112
|
+
out = out.split(base).join("./");
|
|
113
|
+
}
|
|
114
|
+
return out.replace(SEALED, "./");
|
|
115
|
+
};
|
|
116
|
+
const ownPage = (url) => {
|
|
117
|
+
if (filesBase === null || typeof url !== "string" || url.indexOf(filesBase) !== 0) {
|
|
118
|
+
return false;
|
|
119
|
+
}
|
|
120
|
+
const path = url.slice(filesBase.length).split("#")[0].split("?")[0];
|
|
121
|
+
const last = path.slice(path.lastIndexOf("/") + 1);
|
|
122
|
+
return last === "" || last.indexOf(".") < 0 || /\.html?$/i.test(last);
|
|
123
|
+
};
|
|
91
124
|
const navigationApi = window.navigation;
|
|
92
125
|
const getterOf = (proto, name) => {
|
|
93
126
|
const descriptor = proto ? Object.getOwnPropertyDescriptor(proto, name) : undefined;
|
|
@@ -105,8 +138,13 @@ export const SHELL_RUNTIME = String.raw`(() => {
|
|
|
105
138
|
navigationApi.addEventListener("navigate", (event) => {
|
|
106
139
|
const destination = applyOf(destinationOf, event, []);
|
|
107
140
|
if (!applyOf(sameDocumentOf, destination, []) && applyOf(navigationTypeOf, event, []) !== "reload") {
|
|
141
|
+
const url = urlOf === null ? "" : String(applyOf(urlOf, destination, []));
|
|
142
|
+
if (ownPage(url)) {
|
|
143
|
+
navigating(url);
|
|
144
|
+
return;
|
|
145
|
+
}
|
|
108
146
|
applyOf(preventNavigation, event, []);
|
|
109
|
-
navigationBlocked(
|
|
147
|
+
navigationBlocked(url);
|
|
110
148
|
}
|
|
111
149
|
}, true);
|
|
112
150
|
}
|
|
@@ -321,7 +359,7 @@ export const SHELL_RUNTIME = String.raw`(() => {
|
|
|
321
359
|
// the person makes (their keys, their menu) copies their selection as the browser makes it: no
|
|
322
360
|
// copy or cut listener of the content's runs, so none can swap what goes on the clipboard.
|
|
323
361
|
const noClipboard = function () {
|
|
324
|
-
return Promise.reject(new DOMException("Content can't use the clipboard here" + (declared("copyText") ? ": call copyText(text) from a click" : ""), "NotAllowedError"));
|
|
362
|
+
return Promise.reject(new DOMException("Content can't use the clipboard here" + (declared("copyText") ? (plan.runtime ? ': call (await porthole.use("clipboard")).copy(text) from a click' : ": call copyText(text) from a click") : ""), "NotAllowedError"));
|
|
325
363
|
};
|
|
326
364
|
if (typeof Clipboard === "function") {
|
|
327
365
|
for (const name of ["write", "writeText", "read", "readText"]) {
|
|
@@ -479,7 +517,7 @@ export const SHELL_RUNTIME = String.raw`(() => {
|
|
|
479
517
|
return;
|
|
480
518
|
}
|
|
481
519
|
reported += 1;
|
|
482
|
-
send({ method: "notifications/message", params: { level: "error", logger: "porthole", data:
|
|
520
|
+
send({ method: "notifications/message", params: { level: "error", logger: "porthole", data: ownAddresses(message).slice(0, 2000) } });
|
|
483
521
|
};
|
|
484
522
|
// Nothing secret is ever said from here, so any parent may hear it; what it hears is the
|
|
485
523
|
// content's word, which the host gates before it acts on it.
|
|
@@ -500,8 +538,41 @@ export const SHELL_RUNTIME = String.raw`(() => {
|
|
|
500
538
|
return;
|
|
501
539
|
}
|
|
502
540
|
reported += 1;
|
|
503
|
-
post({ method: "porthole/navigation-blocked", params: { url: url.slice(0, 4096) } });
|
|
541
|
+
post({ method: "porthole/navigation-blocked", params: { url: ownAddresses(url).slice(0, 4096) } });
|
|
504
542
|
};
|
|
543
|
+
// Another page of the set opening in the frame (P084): the host takes the next load for it.
|
|
544
|
+
navigating = (url) => {
|
|
545
|
+
post({ method: "porthole/navigating", params: { url: ownAddresses(url).slice(0, 4096) } });
|
|
546
|
+
};
|
|
547
|
+
// A sealed files' address opens the page's files on its own for a while (P083): renewed before
|
|
548
|
+
// it ends, the page moved to the new one in place (the same page, the same history entry). Its
|
|
549
|
+
// modules keep the address they loaded from; the server serves their own loads till the session
|
|
550
|
+
// ends.
|
|
551
|
+
if (filesBase !== null && typeof plan.files.expires === "number") {
|
|
552
|
+
const nativeFetch = window.fetch.bind(window);
|
|
553
|
+
const replace = History.prototype.replaceState;
|
|
554
|
+
const renewIn = (expires) => Math.max(30000, expires - Date.now() - 300000);
|
|
555
|
+
const renew = () => {
|
|
556
|
+
nativeFetch(filesBase + "__porthole/renew", { credentials: "omit", cache: "no-store" })
|
|
557
|
+
.then((answer) => (answer.ok ? answer.json() : null))
|
|
558
|
+
.then((renewed) => {
|
|
559
|
+
if (!renewed || typeof renewed.base !== "string" || typeof renewed.expires !== "number" || renewed.base.indexOf(location.origin + "/__porthole/f/") !== 0 || renewed.base.slice(-1) !== "/") {
|
|
560
|
+
return;
|
|
561
|
+
}
|
|
562
|
+
const here = location.href;
|
|
563
|
+
if (here.indexOf(filesBase) === 0) {
|
|
564
|
+
try {
|
|
565
|
+
applyOf(replace, history, [history.state, "", renewed.base + here.slice(filesBase.length)]);
|
|
566
|
+
} catch (_) {}
|
|
567
|
+
}
|
|
568
|
+
filesBase = renewed.base;
|
|
569
|
+
filesBases.push(renewed.base);
|
|
570
|
+
setTimeout(renew, renewIn(renewed.expires));
|
|
571
|
+
})
|
|
572
|
+
.catch(() => setTimeout(renew, 60000));
|
|
573
|
+
};
|
|
574
|
+
setTimeout(renew, renewIn(plan.files.expires));
|
|
575
|
+
}
|
|
505
576
|
|
|
506
577
|
// A parsed tree's scripts are held (each replaced by a numbered marker) and run later, in order,
|
|
507
578
|
// as the page's parser would run them: each made again, live, in its marker's place, and each
|
|
@@ -728,41 +799,6 @@ export const SHELL_RUNTIME = String.raw`(() => {
|
|
|
728
799
|
return !(capability && capability.userActivation) || !activation || activation.isActive;
|
|
729
800
|
};
|
|
730
801
|
const refuse = (message) => Promise.reject(new Error(message));
|
|
731
|
-
if (declared("sendPrompt")) {
|
|
732
|
-
lock(window, "sendPrompt", (text) => {
|
|
733
|
-
if (!gestured("sendPrompt")) {
|
|
734
|
-
return refuse("sendPrompt needs a click: call it from a button's handler");
|
|
735
|
-
}
|
|
736
|
-
const words = String(text);
|
|
737
|
-
if (words.trim() === "" || words.length > plan.maxPromptChars) {
|
|
738
|
-
return refuse("sendPrompt takes 1 to " + plan.maxPromptChars + " characters");
|
|
739
|
-
}
|
|
740
|
-
return request("ui/message", { role: "user", content: [{ type: "text", text: words }] }).then(
|
|
741
|
-
(result) => !(result && result.isError),
|
|
742
|
-
);
|
|
743
|
-
});
|
|
744
|
-
}
|
|
745
|
-
if (declared("copyText")) {
|
|
746
|
-
lock(window, "copyText", (text) => {
|
|
747
|
-
if (!gestured("copyText")) {
|
|
748
|
-
return refuse("copyText needs a click: call it from a button's handler");
|
|
749
|
-
}
|
|
750
|
-
const words = String(text);
|
|
751
|
-
if (words === "" || words.length > plan.maxCopyChars) {
|
|
752
|
-
return refuse("copyText takes 1 to " + plan.maxCopyChars + " characters");
|
|
753
|
-
}
|
|
754
|
-
return request("porthole/copy-text", { text: words }).then((result) => !(result && result.isError));
|
|
755
|
-
});
|
|
756
|
-
}
|
|
757
|
-
if (declared("openLink")) {
|
|
758
|
-
lock(window, "openLink", (url) => {
|
|
759
|
-
if (!gestured("openLink")) {
|
|
760
|
-
return refuse("openLink needs a click: call it from a link's or button's handler");
|
|
761
|
-
}
|
|
762
|
-
return request("ui/open-link", { url: String(url) }).then((result) => !(result && result.isError));
|
|
763
|
-
});
|
|
764
|
-
}
|
|
765
|
-
|
|
766
802
|
// Data (P079): readData reads a resource the host names, subscribeData follows one, through
|
|
767
803
|
// MCP's resources/* requests, which the host gates (the viewer's consent, a rate). A value is the
|
|
768
804
|
// first content's: JSON parsed when it says it is JSON, else its text.
|
|
@@ -786,9 +822,10 @@ export const SHELL_RUNTIME = String.raw`(() => {
|
|
|
786
822
|
const later = (error) => setTimeout(() => {
|
|
787
823
|
throw error;
|
|
788
824
|
});
|
|
789
|
-
|
|
790
|
-
|
|
791
|
-
|
|
825
|
+
// Reads a resource (readData, the runtime's data.read).
|
|
826
|
+
const readValue = (uri) => request("resources/read", { uri: String(uri) }).then(valueOf);
|
|
827
|
+
// Follows one (subscribeData, the runtime's data.subscribe), where the config declares it.
|
|
828
|
+
let follow = null;
|
|
792
829
|
if (declared("subscribeData")) {
|
|
793
830
|
// One subscription per URI, however many follow it; a read at a time, one more if it changed
|
|
794
831
|
// meanwhile; a late follower gets the last value at once.
|
|
@@ -842,7 +879,7 @@ export const SHELL_RUNTIME = String.raw`(() => {
|
|
|
842
879
|
refresh(entry);
|
|
843
880
|
}
|
|
844
881
|
};
|
|
845
|
-
|
|
882
|
+
follow = (uri, onData, onError) => {
|
|
846
883
|
if (typeof onData !== "function") {
|
|
847
884
|
throw new TypeError("subscribeData(uri, onData, onError): onData must be a function");
|
|
848
885
|
}
|
|
@@ -886,9 +923,19 @@ export const SHELL_RUNTIME = String.raw`(() => {
|
|
|
886
923
|
request("resources/unsubscribe", { uri: key }).catch(() => {});
|
|
887
924
|
}
|
|
888
925
|
};
|
|
889
|
-
}
|
|
926
|
+
};
|
|
890
927
|
}
|
|
891
928
|
|
|
929
|
+
|
|
930
|
+
// The capability runtime's hooks (P085): the host's offer from the handshake (null: no host
|
|
931
|
+
// answered), and a watch's updates. The runtime, where the config has one, takes them.
|
|
932
|
+
let runtimeOffer = (_offer) => {};
|
|
933
|
+
let runtimeEvent = (_params) => {};
|
|
934
|
+
|
|
935
|
+
__LEGACY__
|
|
936
|
+
|
|
937
|
+
__RUNTIME__
|
|
938
|
+
|
|
892
939
|
window.addEventListener("error", (event) => {
|
|
893
940
|
const error = event.error;
|
|
894
941
|
const where = event.lineno ? " (line " + event.lineno + ")" : "";
|
|
@@ -923,6 +970,16 @@ export const SHELL_RUNTIME = String.raw`(() => {
|
|
|
923
970
|
try {
|
|
924
971
|
url = new URL(href, document.baseURI).href;
|
|
925
972
|
} catch (_) {}
|
|
973
|
+
// A page of the set opens in the frame, whatever its target (P084); any other file of the
|
|
974
|
+
// set never opens: its address carries the frame's access.
|
|
975
|
+
if (ownPage(url)) {
|
|
976
|
+
location.assign(url);
|
|
977
|
+
return;
|
|
978
|
+
}
|
|
979
|
+
if (filesBase !== null && url.indexOf(filesBase) === 0) {
|
|
980
|
+
navigationBlocked(url);
|
|
981
|
+
return;
|
|
982
|
+
}
|
|
926
983
|
if (/^https?:/i.test(url) && typeof window.openLink === "function") {
|
|
927
984
|
window.openLink(url).catch(() => {});
|
|
928
985
|
}
|
|
@@ -1069,6 +1126,9 @@ export const SHELL_RUNTIME = String.raw`(() => {
|
|
|
1069
1126
|
resourceUpdated(params.uri);
|
|
1070
1127
|
}
|
|
1071
1128
|
break;
|
|
1129
|
+
case "porthole/event":
|
|
1130
|
+
runtimeEvent(params);
|
|
1131
|
+
break;
|
|
1072
1132
|
case "ui/resource-teardown":
|
|
1073
1133
|
case "ping":
|
|
1074
1134
|
if (data.id !== undefined) {
|
|
@@ -1096,7 +1156,12 @@ export const SHELL_RUNTIME = String.raw`(() => {
|
|
|
1096
1156
|
let initialized = false;
|
|
1097
1157
|
let tries = 0;
|
|
1098
1158
|
const initialize = () => {
|
|
1099
|
-
if (initialized
|
|
1159
|
+
if (initialized) {
|
|
1160
|
+
return;
|
|
1161
|
+
}
|
|
1162
|
+
if (tries >= 40) {
|
|
1163
|
+
// No host answered: the runtime has nothing to offer.
|
|
1164
|
+
runtimeOffer(null);
|
|
1100
1165
|
return;
|
|
1101
1166
|
}
|
|
1102
1167
|
tries += 1;
|
|
@@ -1109,6 +1174,9 @@ export const SHELL_RUNTIME = String.raw`(() => {
|
|
|
1109
1174
|
return;
|
|
1110
1175
|
}
|
|
1111
1176
|
initialized = true;
|
|
1177
|
+
const capabilities = result && result.hostCapabilities;
|
|
1178
|
+
const experimental = capabilities && capabilities.experimental;
|
|
1179
|
+
runtimeOffer(experimental && typeof experimental === "object" ? experimental["porthole/runtime"] : null);
|
|
1112
1180
|
applyTheme(result && result.hostContext);
|
|
1113
1181
|
notify("ui/notifications/initialized", {});
|
|
1114
1182
|
schedule();
|
package/src/shell/use.ts
ADDED
|
@@ -0,0 +1,235 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The capability runtime in the frame (P085), spliced into the shell's runtime (`__RUNTIME__`)
|
|
3
|
+
* where the config has one (`config.runtime`). Content gets one global, `porthole`, whose only
|
|
4
|
+
* member is `use(name)`: a promise of a frozen namespace of the capability's methods, or null when
|
|
5
|
+
* the capability isn't there for this page (not offered, not declared, no host): the reasons are
|
|
6
|
+
* indistinguishable. Permission problems come at call time, as a rejected promise whose error has
|
|
7
|
+
* a stable `code` (P080, P087) and a sentence to show.
|
|
8
|
+
*
|
|
9
|
+
* The host's offer comes in the handshake (MCP Apps' experimental host capabilities,
|
|
10
|
+
* `porthole/runtime`): which capabilities, which methods. Calls go as `porthole/call` (own-prefixed,
|
|
11
|
+
* P002), `data.read` and `data.subscribe` as MCP's own resource requests (the cache and the
|
|
12
|
+
* subscriptions of P079); a watch's updates come as `porthole/event`. The host's bridge decides
|
|
13
|
+
* every call: nothing here is a wall, since it shares the content's realm.
|
|
14
|
+
*/
|
|
15
|
+
export const USE_RUNTIME = String.raw`
|
|
16
|
+
// The capability runtime (P085): porthole.use(name) -> a frozen namespace, or null.
|
|
17
|
+
// The host's offer: undefined until the handshake says (or gives up: null). A late answer is
|
|
18
|
+
// still taken, for the calls to use after it (after the review).
|
|
19
|
+
let offered = undefined;
|
|
20
|
+
const waiting = new Set();
|
|
21
|
+
runtimeOffer = (given) => {
|
|
22
|
+
const capabilities = given !== null && typeof given === "object" && given.capabilities !== null && typeof given.capabilities === "object" ? given.capabilities : null;
|
|
23
|
+
if (capabilities !== null || offered === undefined) {
|
|
24
|
+
offered = capabilities;
|
|
25
|
+
}
|
|
26
|
+
for (const wake of Array.from(waiting)) {
|
|
27
|
+
wake();
|
|
28
|
+
}
|
|
29
|
+
waiting.clear();
|
|
30
|
+
};
|
|
31
|
+
// A use waits for the handshake a few seconds at most, then is null (no host is answering).
|
|
32
|
+
const ready = () =>
|
|
33
|
+
offered !== undefined
|
|
34
|
+
? Promise.resolve()
|
|
35
|
+
: new Promise((resolve) => {
|
|
36
|
+
waiting.add(resolve);
|
|
37
|
+
setTimeout(resolve, 3000);
|
|
38
|
+
});
|
|
39
|
+
// Framed by a page that isn't one of this frame's hosts: nothing will answer (where the engine
|
|
40
|
+
// says who framed it).
|
|
41
|
+
const framedByHost = () => {
|
|
42
|
+
const ancestors = location.ancestorOrigins;
|
|
43
|
+
// "null": the engine masks it (a no-referrer frame): unknown, not a stranger.
|
|
44
|
+
return !ancestors || ancestors.length === 0 || ancestors[0] === "null" || plan.origins.indexOf(ancestors[0]) !== -1;
|
|
45
|
+
};
|
|
46
|
+
const NativeBlob = typeof Blob === "function" ? Blob : null;
|
|
47
|
+
const NativeArrayBuffer = ArrayBuffer;
|
|
48
|
+
const coded = (code, message) => {
|
|
49
|
+
const error = new Error(message);
|
|
50
|
+
error.code = code;
|
|
51
|
+
return error;
|
|
52
|
+
};
|
|
53
|
+
// A call through the host; its value, or a rejection with the refusal's code.
|
|
54
|
+
const call = (capability, method, args) =>
|
|
55
|
+
request("porthole/call", { capability, method, args }).then((result) =>
|
|
56
|
+
result !== null && typeof result === "object" ? result.value : undefined,
|
|
57
|
+
);
|
|
58
|
+
// What needs a click, refused here before it goes (the host checks again: P021).
|
|
59
|
+
const clicked = (serves, what) => (gestured(serves) ? null : Promise.reject(coded("not_allowed", what + " needs a click: call it from a button's handler")));
|
|
60
|
+
// Bytes as base64, for what crosses the frame as JSON.
|
|
61
|
+
const bytesOf = (data) => {
|
|
62
|
+
if (NativeBlob !== null && data instanceof NativeBlob) {
|
|
63
|
+
return data.arrayBuffer().then((buffer) => new Uint8Array(buffer));
|
|
64
|
+
}
|
|
65
|
+
if (data instanceof NativeArrayBuffer) {
|
|
66
|
+
return Promise.resolve(new Uint8Array(data));
|
|
67
|
+
}
|
|
68
|
+
if (ArrayBuffer.isView(data)) {
|
|
69
|
+
return Promise.resolve(new Uint8Array(data.buffer, data.byteOffset, data.byteLength));
|
|
70
|
+
}
|
|
71
|
+
return null;
|
|
72
|
+
};
|
|
73
|
+
const base64Of = (bytes) => {
|
|
74
|
+
let text = "";
|
|
75
|
+
for (let at = 0; at < bytes.length; at += 32768) {
|
|
76
|
+
text += String.fromCharCode.apply(null, Array.from(bytes.subarray(at, at + 32768)));
|
|
77
|
+
}
|
|
78
|
+
return btoa(text);
|
|
79
|
+
};
|
|
80
|
+
// A file's content: text as it is, bytes as base64, null as null (a removal).
|
|
81
|
+
const fileOf = (value) => {
|
|
82
|
+
if (value === null || typeof value === "string") {
|
|
83
|
+
return Promise.resolve(value === null ? null : { text: value });
|
|
84
|
+
}
|
|
85
|
+
const bytes = bytesOf(value);
|
|
86
|
+
return bytes === null ? Promise.reject(coded("not_allowed", "A file is text, a Blob, an ArrayBuffer or bytes")) : bytes.then((each) => ({ base64: base64Of(each) }));
|
|
87
|
+
};
|
|
88
|
+
const record = (value) => (value !== null && typeof value === "object" ? value : {});
|
|
89
|
+
// Watches (db.onSnapshot): by the id this frame gives each, its listener.
|
|
90
|
+
const watchers = new Map();
|
|
91
|
+
// A watch's id is this page's own, at random: a page that follows another on the same
|
|
92
|
+
// transport can't be handed its watches (after the review).
|
|
93
|
+
const watchId = () => {
|
|
94
|
+
const bytes = new Uint8Array(8);
|
|
95
|
+
crypto.getRandomValues(bytes);
|
|
96
|
+
return "w" + Array.from(bytes, (each) => each.toString(16).padStart(2, "0")).join("");
|
|
97
|
+
};
|
|
98
|
+
runtimeEvent = (params) => {
|
|
99
|
+
const watcher = typeof params.watch === "string" ? watchers.get(params.watch) : undefined;
|
|
100
|
+
if (watcher === undefined) {
|
|
101
|
+
return;
|
|
102
|
+
}
|
|
103
|
+
try {
|
|
104
|
+
watcher.onData(params.data);
|
|
105
|
+
} catch (error) {
|
|
106
|
+
later(error);
|
|
107
|
+
}
|
|
108
|
+
};
|
|
109
|
+
const watch = (capability, method, args, onData, onError) => {
|
|
110
|
+
if (typeof onData !== "function") {
|
|
111
|
+
throw new TypeError(capability + "." + method + ": onData must be a function");
|
|
112
|
+
}
|
|
113
|
+
const id = watchId();
|
|
114
|
+
watchers.set(id, { onData });
|
|
115
|
+
request("porthole/call", { capability, method, args, watch: id }).catch((error) => {
|
|
116
|
+
watchers.delete(id);
|
|
117
|
+
if (typeof onError === "function") {
|
|
118
|
+
try {
|
|
119
|
+
onError(error);
|
|
120
|
+
} catch (thrown) {
|
|
121
|
+
later(thrown);
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
});
|
|
125
|
+
return () => {
|
|
126
|
+
if (watchers.delete(id)) {
|
|
127
|
+
notify("porthole/unwatch", { watch: id });
|
|
128
|
+
}
|
|
129
|
+
};
|
|
130
|
+
};
|
|
131
|
+
const METHODS = {
|
|
132
|
+
user: { get: () => call("user", "get", {}) },
|
|
133
|
+
comments: {
|
|
134
|
+
open: (anchor) => clicked("comments", "comments.open") || call("comments", "open", { anchor: typeof anchor === "string" ? { name: anchor } : record(anchor) }),
|
|
135
|
+
},
|
|
136
|
+
clipboard: { copy: (text) => clicked("copyText", "clipboard.copy") || call("clipboard", "copy", { text: String(text) }) },
|
|
137
|
+
links: { open: (url) => clicked("openLink", "links.open") || call("links", "open", { url: String(url) }) },
|
|
138
|
+
downloads: {
|
|
139
|
+
save: (file) => {
|
|
140
|
+
const given = record(file);
|
|
141
|
+
const waiting = clicked("downloadFile", "downloads.save");
|
|
142
|
+
if (waiting !== null) {
|
|
143
|
+
return waiting;
|
|
144
|
+
}
|
|
145
|
+
const content = given.data !== undefined ? given.data : given.text !== undefined ? String(given.text) : null;
|
|
146
|
+
return fileOf(content).then((body) => call("downloads", "save", { file: Object.assign({ name: given.name, type: given.type }, record(body)) }));
|
|
147
|
+
},
|
|
148
|
+
},
|
|
149
|
+
chat: { send: (text) => clicked("sendPrompt", "chat.send") || call("chat", "send", { text: String(text) }) },
|
|
150
|
+
data: {
|
|
151
|
+
read: (uri) => readValue(uri),
|
|
152
|
+
subscribe: (uri, onData, onError) => (follow === null ? null : follow(uri, onData, onError)),
|
|
153
|
+
call: (name, args) => call("data", "call", { name: String(name), arguments: args === undefined ? {} : args }),
|
|
154
|
+
},
|
|
155
|
+
context: { set: (update) => call("context", "set", record(update)) },
|
|
156
|
+
artifact: {
|
|
157
|
+
get: () => call("artifact", "get", {}),
|
|
158
|
+
publish: (change) => {
|
|
159
|
+
const given = record(change);
|
|
160
|
+
const files = record(given.files);
|
|
161
|
+
const names = Object.keys(files);
|
|
162
|
+
return Promise.all(names.map((name) => fileOf(files[name]))).then((bodies) => {
|
|
163
|
+
const out = {};
|
|
164
|
+
names.forEach((name, index) => {
|
|
165
|
+
out[name] = bodies[index];
|
|
166
|
+
});
|
|
167
|
+
return call("artifact", "publish", { base: given.base, files: out, entry: given.entry, label: given.label, note: given.note });
|
|
168
|
+
});
|
|
169
|
+
},
|
|
170
|
+
},
|
|
171
|
+
assets: {
|
|
172
|
+
list: () => call("assets", "list", {}),
|
|
173
|
+
upload: (file, options) => {
|
|
174
|
+
const name = record(options).name !== undefined ? record(options).name : file && typeof file.name === "string" ? file.name : undefined;
|
|
175
|
+
const bytes = bytesOf(file);
|
|
176
|
+
return bytes === null ? Promise.reject(coded("not_allowed", "assets.upload takes a File, a Blob or bytes")) : bytes.then((each) => call("assets", "upload", { name, base64: base64Of(each) }));
|
|
177
|
+
},
|
|
178
|
+
delete: (id) => call("assets", "delete", { id: String(id) }),
|
|
179
|
+
// The address that loads an asset in this page now (P091): in a frame, under its own sealed
|
|
180
|
+
// files' address, which every engine sends; elsewhere /_blob/<id>. Never stored: it carries
|
|
181
|
+
// this page's access.
|
|
182
|
+
url: (id) => {
|
|
183
|
+
const asset = String(id);
|
|
184
|
+
if (!/^[0-9a-f]{32}$/.test(asset)) {
|
|
185
|
+
throw new TypeError("assets.url(id): an asset's id is 32 lowercase hex characters");
|
|
186
|
+
}
|
|
187
|
+
return filesBase !== null && filesBase.indexOf("/__porthole/f/") !== -1 ? filesBase + "__porthole/blob/" + asset : "/_blob/" + asset;
|
|
188
|
+
},
|
|
189
|
+
},
|
|
190
|
+
db: {
|
|
191
|
+
get: (path) => call("db", "get", { path }),
|
|
192
|
+
set: (path, data, options) => call("db", "set", { path, data, ifVersion: record(options).ifVersion }),
|
|
193
|
+
update: (path, data, options) => call("db", "update", { path, data, ifVersion: record(options).ifVersion }),
|
|
194
|
+
delete: (path, options) => call("db", "delete", { path, ifVersion: record(options).ifVersion }),
|
|
195
|
+
query: (collection, query) => call("db", "query", Object.assign({ collection }, record(query))),
|
|
196
|
+
batch: (writes) => call("db", "batch", { writes }),
|
|
197
|
+
onSnapshot: (path, onData, onError) => watch("db", "watch", { path }, onData, onError),
|
|
198
|
+
},
|
|
199
|
+
};
|
|
200
|
+
// A runtime method's name in the namespace, where it differs from the contract's.
|
|
201
|
+
const RENAMED = { db: { watch: "onSnapshot" } };
|
|
202
|
+
const namespaces = new Map();
|
|
203
|
+
const use = (name) => {
|
|
204
|
+
if (window.parent === window || !framedByHost() || typeof name !== "string" || !Object.prototype.hasOwnProperty.call(METHODS, name)) {
|
|
205
|
+
return Promise.resolve(null);
|
|
206
|
+
}
|
|
207
|
+
return ready().then(() => {
|
|
208
|
+
const methods = offered !== undefined && offered !== null && Array.isArray(offered[name]) ? offered[name] : null;
|
|
209
|
+
if (methods === null) {
|
|
210
|
+
return null;
|
|
211
|
+
}
|
|
212
|
+
if (!namespaces.has(name)) {
|
|
213
|
+
const space = {};
|
|
214
|
+
const renamed = RENAMED[name] || {};
|
|
215
|
+
for (const each of methods) {
|
|
216
|
+
const key = Object.prototype.hasOwnProperty.call(renamed, each) ? renamed[each] : each;
|
|
217
|
+
if (typeof each === "string" && Object.prototype.hasOwnProperty.call(METHODS[name], key)) {
|
|
218
|
+
const call = METHODS[name][key];
|
|
219
|
+
// A method whose own gates want a gesture (after the review): refused here without one.
|
|
220
|
+
const gated = Array.isArray(plan.methodActivation) && plan.methodActivation.indexOf(name + "." + each) !== -1;
|
|
221
|
+
space[key] = gated
|
|
222
|
+
? function () {
|
|
223
|
+
const activation = navigator.userActivation;
|
|
224
|
+
return activation && !activation.isActive ? Promise.reject(coded("not_allowed", name + "." + key + " needs a click: call it from a button's handler")) : call.apply(null, arguments);
|
|
225
|
+
}
|
|
226
|
+
: call;
|
|
227
|
+
}
|
|
228
|
+
}
|
|
229
|
+
namespaces.set(name, Object.freeze(space));
|
|
230
|
+
}
|
|
231
|
+
return namespaces.get(name);
|
|
232
|
+
}, () => null);
|
|
233
|
+
};
|
|
234
|
+
lock(window, "porthole", Object.freeze({ use }));
|
|
235
|
+
`;
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
// Porthole capability runtime, contract 1: artifact (this artifact itself). Declare it: { artifact: {} }.
|
|
2
|
+
// Use it when the page is the record: a checklist, a plan, a document someone edits in place.
|
|
3
|
+
|
|
4
|
+
interface PortholeArtifactFile {
|
|
5
|
+
readonly path: string;
|
|
6
|
+
readonly size: number;
|
|
7
|
+
readonly sha256: string;
|
|
8
|
+
}
|
|
9
|
+
|
|
10
|
+
interface PortholeArtifactVersion {
|
|
11
|
+
/** The version's id: what a publish names as its base. */
|
|
12
|
+
readonly version: string;
|
|
13
|
+
readonly number?: number;
|
|
14
|
+
/** The page it opens at ("index.html"). */
|
|
15
|
+
readonly entry: string;
|
|
16
|
+
readonly files: readonly PortholeArtifactFile[];
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
interface PortholeArtifactPublish {
|
|
20
|
+
/** The version you read and changed (from get()). If it moved, publish rejects with conflict. */
|
|
21
|
+
readonly base: string;
|
|
22
|
+
/**
|
|
23
|
+
* A patch on base's files, by path: text, bytes (a Blob, an ArrayBuffer, a typed array), or
|
|
24
|
+
* null to remove one; files not named are kept. A page sends its whole document, as it should
|
|
25
|
+
* be served. At most 255 files.
|
|
26
|
+
*/
|
|
27
|
+
readonly files: Readonly<Record<string, string | Blob | ArrayBuffer | ArrayBufferView | null>>;
|
|
28
|
+
readonly entry?: string;
|
|
29
|
+
/** At most 60 characters. */
|
|
30
|
+
readonly label?: string;
|
|
31
|
+
/** At most 500 characters. */
|
|
32
|
+
readonly note?: string;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
interface PortholeArtifact {
|
|
36
|
+
/** The current version and its files (fetch a file by its relative path). Level: view. */
|
|
37
|
+
get(): Promise<PortholeArtifactVersion>;
|
|
38
|
+
/**
|
|
39
|
+
* Publishes a new version of this artifact, from a click; the app asks the person first. The
|
|
40
|
+
* page can't change what it declares. On conflict: get() again, merge, publish again. Level:
|
|
41
|
+
* admin.
|
|
42
|
+
*/
|
|
43
|
+
publish(
|
|
44
|
+
change: PortholeArtifactPublish,
|
|
45
|
+
): Promise<{ readonly version: string; readonly number?: number }>;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
interface PortholeCapabilities {
|
|
49
|
+
artifact: PortholeArtifact;
|
|
50
|
+
}
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
// Porthole capability runtime, contract 1: assets (the artifact's asset library). Declare it: { assets: {} }.
|
|
2
|
+
// Assets live outside every version, at "/_blob/<id>" on the page's own origin: keep that url (or
|
|
3
|
+
// the id) in your data, and show it with assets.url(id). Images, media and fonts load; scripts and
|
|
4
|
+
// stylesheets only where the app lets only admins upload, and only those an admin added. Not for
|
|
5
|
+
// files that version with the page: publish those with it.
|
|
6
|
+
|
|
7
|
+
interface PortholeAsset {
|
|
8
|
+
/** 32 hex characters. */
|
|
9
|
+
readonly id: string;
|
|
10
|
+
/** "/_blob/<id>": use it as given. */
|
|
11
|
+
readonly url: string;
|
|
12
|
+
readonly name: string;
|
|
13
|
+
/** Porthole's type for the name's extension. */
|
|
14
|
+
readonly type: string;
|
|
15
|
+
readonly size: number;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
interface PortholeAssets {
|
|
19
|
+
/** The library, people's uploads through the page included. Level: view. */
|
|
20
|
+
list(): Promise<readonly PortholeAsset[]>;
|
|
21
|
+
/**
|
|
22
|
+
* Adds a file (a File from an <input type="file">, a Blob, bytes) under its name (a File's own,
|
|
23
|
+
* or options.name): an image, media, a font, a PDF, text or data, never HTML; a script or a
|
|
24
|
+
* stylesheet only where uploads are the admins'. The app may ask the person first. Level: admin,
|
|
25
|
+
* unless the app lets people who interact upload.
|
|
26
|
+
*/
|
|
27
|
+
upload(
|
|
28
|
+
file: Blob | ArrayBuffer | ArrayBufferView,
|
|
29
|
+
options?: { readonly name?: string },
|
|
30
|
+
): Promise<PortholeAsset>;
|
|
31
|
+
/**
|
|
32
|
+
* The address that loads an asset in this page now: put it in src or href when you show it.
|
|
33
|
+
* Store the id (or "/_blob/<id>"), never this: it carries this page's access. A "/_blob/<id>"
|
|
34
|
+
* written in the page loads too, except in some browsers' frames (Safari's); this always does.
|
|
35
|
+
*/
|
|
36
|
+
url(id: string): string;
|
|
37
|
+
/** Removes one, from a click; the app asks the person first. Level: admin. */
|
|
38
|
+
delete(id: string): Promise<boolean>;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
interface PortholeCapabilities {
|
|
42
|
+
assets: PortholeAssets;
|
|
43
|
+
}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
// Porthole capability runtime, contract 1: chat. Declare it: { chat: {} }.
|
|
2
|
+
|
|
3
|
+
interface PortholeChat {
|
|
4
|
+
/**
|
|
5
|
+
* Sends text to the agent as the person's message ("explain this point"). Call it from a click.
|
|
6
|
+
* Resolves true if it was sent. Level: interact.
|
|
7
|
+
*/
|
|
8
|
+
send(text: string): Promise<boolean>;
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
interface PortholeCapabilities {
|
|
12
|
+
chat: PortholeChat;
|
|
13
|
+
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
// Porthole capability runtime, contract 1: clipboard. Built in: never declare it.
|
|
2
|
+
|
|
3
|
+
interface PortholeClipboard {
|
|
4
|
+
/**
|
|
5
|
+
* Copies text to the person's clipboard (at most 20,000 characters); the app shows them what
|
|
6
|
+
* was copied. Nothing else in the page can write the clipboard. Call it from a click.
|
|
7
|
+
* Resolves true if it was copied. Level: view.
|
|
8
|
+
*/
|
|
9
|
+
copy(text: string): Promise<boolean>;
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
interface PortholeCapabilities {
|
|
13
|
+
clipboard: PortholeClipboard;
|
|
14
|
+
}
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
// Porthole capability runtime, contract 1: comments. Built in: never declare it.
|
|
2
|
+
|
|
3
|
+
/** Where a comment goes, in the page's own words. */
|
|
4
|
+
interface PortholeCommentAnchor {
|
|
5
|
+
/** A stable name the page chose: "slide-3", "refs/a.md#L12" (at most 256 characters). */
|
|
6
|
+
readonly name: string;
|
|
7
|
+
/** What the app shows for it (at most 200). */
|
|
8
|
+
readonly label?: string;
|
|
9
|
+
/** The text the comment is about (at most 2,000). */
|
|
10
|
+
readonly quote?: string;
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
interface PortholeComments {
|
|
14
|
+
/**
|
|
15
|
+
* Opens the app's comment composer at the anchor (a name alone is { name }). The person writes
|
|
16
|
+
* and posts it in the app. Resolves true if the composer opened. Write-only: a page never reads
|
|
17
|
+
* comments. Call it from a click. Level: view.
|
|
18
|
+
*/
|
|
19
|
+
open(anchor: PortholeCommentAnchor | string): Promise<boolean>;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
interface PortholeCapabilities {
|
|
23
|
+
comments: PortholeComments;
|
|
24
|
+
}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
// Porthole capability runtime, contract 1: context. Declare it: { context: {} }.
|
|
2
|
+
|
|
3
|
+
interface PortholeContextUpdate {
|
|
4
|
+
/** MCP content blocks: [{ type: "text", text: "…" }]. */
|
|
5
|
+
readonly content?: readonly unknown[];
|
|
6
|
+
readonly structuredContent?: Record<string, unknown>;
|
|
7
|
+
}
|
|
8
|
+
|
|
9
|
+
interface PortholeContext {
|
|
10
|
+
/** Tells the agent what the person is looking at, for its next turns (replaces the last). Level: interact. */
|
|
11
|
+
set(update: PortholeContextUpdate): Promise<unknown>;
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
interface PortholeCapabilities {
|
|
15
|
+
context: PortholeContext;
|
|
16
|
+
}
|