@astrale-os/shell 0.1.1 → 0.2.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Astrale
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/application/apps.d.ts

@@ -0,0 +1,18 @@
+import type { BoundNode, DefOf, NodeRefInput } from '@astrale-os/kernel-client';
+import type { KernelClient } from '../kernel/client';
+import type { AppSession } from './session/session';
+import type { ShellDomainView, ShellSchema } from './view';
+/** An installed `Application` node. */
+export type ApplicationNode = BoundNode<DefOf<ShellSchema, 'Application'>, ShellSchema>;
+export interface AppsNamespace {
+    /** `Application.install(target, space)`, bound as the resulting `Application`. */
+    install(target: string, space: NodeRefInput): Promise<ApplicationNode>;
+    /** The apps installed in `space` (`installed_in` in-edges). */
+    in(space: NodeRefInput): Promise<ApplicationNode[]>;
+    /** Resolve the app node and open its {@link AppSession}. */
+    open(app: NodeRefInput): Promise<AppSession>;
+}
+export declare function createAppsNamespace(kernel: KernelClient, v: ShellDomainView, deps?: {
+    readonly now?: () => number;
+}): AppsNamespace;
+//# sourceMappingURL=apps.d.ts.map

package/dist/application/apps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apps.d.ts","sourceRoot":"","sources":["../../src/application/apps.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAK/E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAA;AAI1D,uCAAuC;AACvC,MAAM,MAAM,eAAe,GAAG,SAAS,CAAC,KAAK,CAAC,WAAW,EAAE,aAAa,CAAC,EAAE,WAAW,CAAC,CAAA;AAEvF,MAAM,WAAW,aAAa;IAC5B,kFAAkF;IAClF,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,eAAe,CAAC,CAAA;IACtE,+DAA+D;IAC/D,EAAE,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAAA;IACnD,4DAA4D;IAC5D,IAAI,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;CAC7C;AAKD,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,YAAY,EACpB,CAAC,EAAE,eAAe,EAClB,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CAAE,GACrC,aAAa,CA6Bf"}

package/dist/application/apps.js

@@ -0,0 +1,35 @@
+import { D } from '@astrale-domains/workspace-schema';
+import { normalizeRef } from '@astrale-os/kernel-client';
+import { openAppSession } from './session/open';
+/** The `installed_in` edge class — traversed to list a space's apps. */
+const INSTALLED_IN_EDGE = D.installed_in.path.class.raw;
+export function createAppsNamespace(kernel, v, deps) {
+    return {
+        async install(target, space) {
+            const created = (await v
+                .view()('Application')
+                .install({
+                target,
+                space: normalizeRef(space),
+            }));
+            const app = await v.view().node('Application', `@${created.id}`);
+            if (!app)
+                throw new Error(`Application.install: app @${created.id} is not readable`);
+            return app;
+        },
+        async in(space) {
+            const page = await kernel.neighbors(normalizeRef(space), INSTALLED_IN_EDGE, 'in');
+            const nodes = await page.all();
+            return nodes.flatMap((n) => {
+                const app = v.bindAs('Application', n);
+                return app ? [app] : [];
+            });
+        },
+        async open(app) {
+            const node = await v.view().node('Application', app);
+            if (!node)
+                throw new Error(`apps.open: application ${normalizeRef(app)} is not readable`);
+            return openAppSession({ kernel, ...(deps?.now ? { now: deps.now } : {}) }, node.id);
+        },
+    };
+}

package/dist/application/namespaces.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The OS-plane namespaces on the Shell — `shell.user` / `shell.spaces` /
+ * `shell.apps`. Framework-free: the shell-react hooks (§12.2) layer over
+ * exactly these. Pure closures over a lazy typed view — constructing this
+ * touches no kernel (safe before a sandboxed shell's `init()`).
+ */
+import type { KernelClient } from '../kernel/client';
+import type { AppsNamespace } from './apps';
+import type { SpacesNamespace } from './spaces';
+import type { UserNamespace } from './user';
+export interface OsNamespaces {
+    readonly user: UserNamespace;
+    readonly spaces: SpacesNamespace;
+    readonly apps: AppsNamespace;
+}
+export interface CreateOsNamespacesDeps {
+    /** Injected clock, threaded into opened `AppSession`s (tests). */
+    readonly now?: () => number;
+}
+export declare function createOsNamespaces(kernel: KernelClient, deps?: CreateOsNamespacesDeps): OsNamespaces;
+//# sourceMappingURL=namespaces.d.ts.map

package/dist/application/namespaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"namespaces.d.ts","sourceRoot":"","sources":["../../src/application/namespaces.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAA;AAC3C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAA;AAO3C,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;IAC5B,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAA;IAChC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;CAC7B;AAED,MAAM,WAAW,sBAAsB;IACrC,kEAAkE;IAClE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CAC5B;AAED,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,YAAY,EACpB,IAAI,CAAC,EAAE,sBAAsB,GAC5B,YAAY,CAOd"}

package/dist/application/namespaces.js

@@ -0,0 +1,12 @@
+import { createAppsNamespace } from './apps';
+import { createSpacesNamespace } from './spaces';
+import { createUserNamespace } from './user';
+import { createShellDomainView } from './view';
+export function createOsNamespaces(kernel, deps) {
+    const v = createShellDomainView(kernel);
+    return {
+        user: createUserNamespace(kernel, v),
+        spaces: createSpacesNamespace(kernel, v),
+        apps: createAppsNamespace(kernel, v, deps),
+    };
+}

package/dist/application/session/open.d.ts

@@ -0,0 +1,19 @@
+import type { KernelClient } from '../../kernel/client';
+import type { AppSession } from './session';
+export interface OpenAppSessionDeps {
+    /** The shell kernel — dispatches AS THE USER, whose signature the delegate step needs. */
+    readonly kernel: KernelClient;
+    /** Injected clock (tests). */
+    readonly now?: () => number;
+}
+/**
+ * Open an app session: run `app::open` for the entry view + first recipe, then
+ * return an {@link AppSession}. The first token mints LAZILY — opening the view
+ * costs no token; `token()` (or `credential.refresh()`) runs the first
+ * delegate/getAccessToken cycle on demand. The {@link MountCredential} is driven
+ * by the mount machinery via `refresh` (no internal timer).
+ */
+export declare function openAppSession(deps: OpenAppSessionDeps, app: {
+    id: string;
+} | string): Promise<AppSession>;
+//# sourceMappingURL=open.d.ts.map

package/dist/application/session/open.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"open.d.ts","sourceRoot":"","sources":["../../../src/application/session/open.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAEvD,OAAO,KAAK,EAAE,UAAU,EAAW,MAAM,WAAW,CAAA;AAYpD,MAAM,WAAW,kBAAkB;IACjC,0FAA0F;IAC1F,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;IAC7B,8BAA8B;IAC9B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CAC5B;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,kBAAkB,EACxB,GAAG,EAAE;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,GAC3B,OAAO,CAAC,UAAU,CAAC,CAuCrB"}

package/dist/application/session/open.js

@@ -0,0 +1,46 @@
+import { createTokenCycle } from './token';
+/**
+ * Open an app session: run `app::open` for the entry view + first recipe, then
+ * return an {@link AppSession}. The first token mints LAZILY — opening the view
+ * costs no token; `token()` (or `credential.refresh()`) runs the first
+ * delegate/getAccessToken cycle on demand. The {@link MountCredential} is driven
+ * by the mount machinery via `refresh` (no internal timer).
+ */
+export async function openAppSession(deps, app) {
+    const appId = typeof app === 'string' ? app : app.id;
+    const { kernel } = deps;
+    const now = deps.now ?? Date.now;
+    const opened = (await kernel.call(`@${appId}::open`, {}));
+    const tokens = createTokenCycle({ kernel, appId, initialRecipe: opened.delegation, now });
+    let disposed = false;
+    async function token() {
+        if (disposed)
+            throw new Error('AppSession is disposed');
+        if (tokens.needsRefresh())
+            return (await tokens.refresh()).token;
+        return tokens.current().token;
+    }
+    const credential = {
+        get token() {
+            return tokens.current()?.token ?? '';
+        },
+        get expiresAt() {
+            return tokens.current()?.expiresAt ?? 0;
+        },
+        refresh: async () => {
+            if (disposed)
+                throw new Error('AppSession is disposed');
+            const next = await tokens.refresh();
+            return { token: next.token, expiresAt: next.expiresAt };
+        },
+    };
+    return {
+        app: appId,
+        view: opened.view,
+        credential,
+        token,
+        dispose() {
+            disposed = true;
+        },
+    };
+}

package/dist/application/session/session.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `AppSession` — the client half of the three-call app-opening protocol
+ * (`app::open` → user-signed `auth.delegate` → `app::getAccessToken`). The
+ * server contract lives in the workspace domain's `Application` methods
+ * (`runtime/application/{open,get-access-token}`).
+ */
+import type { MountCredential } from '../../window/mount/params';
+/** The entry view returned by `app::open`, described for mounting. */
+export interface AppView {
+    readonly id: string;
+    readonly path: string;
+    readonly url?: string;
+    readonly handshake?: string;
+}
+/**
+ * A live app session: the entry view (mount-ready), a mount-compatible
+ * credential, and an on-demand `token()`. `dispose()` is idempotent; after it,
+ * `token()` and `credential.refresh()` reject.
+ */
+export interface AppSession {
+    /** The app node id this session speaks to. */
+    readonly app: string;
+    /** The entry view (from `app::open`), or `null` when the app pins none. */
+    readonly view: AppView | null;
+    /** Shell.mount-compatible credential — `token`/`expiresAt` track the live app token. */
+    readonly credential: MountCredential;
+    /** The current app token; refreshes when within the margin of expiry. Single-flight. */
+    token(): Promise<string>;
+    /** Idempotent teardown. */
+    dispose(): void;
+}
+/** Which protocol step a refresh cycle failed at — carried on {@link AppSessionRefreshError}. */
+export type RefreshStep = 'delegate' | 'getAccessToken';
+/** A refresh cycle that failed, naming the step; prior session state is preserved. */
+export declare class AppSessionRefreshError extends Error {
+    readonly step: RefreshStep;
+    constructor(step: RefreshStep, app: string, options?: {
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/application/session/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../src/application/session/session.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAEhE,sEAAsE;AACtE,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,8CAA8C;IAC9C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAA;IAC7B,wFAAwF;IACxF,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAA;IACpC,wFAAwF;IACxF,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;IACxB,2BAA2B;IAC3B,OAAO,IAAI,IAAI,CAAA;CAChB;AAED,iGAAiG;AACjG,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,gBAAgB,CAAA;AAEvD,sFAAsF;AACtF,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;IAC1B,YAAY,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAIxE;CACF"}

package/dist/application/session/session.js

@@ -0,0 +1,9 @@
+/** A refresh cycle that failed, naming the step; prior session state is preserved. */
+export class AppSessionRefreshError extends Error {
+    step;
+    constructor(step, app, options) {
+        super(`AppSession token refresh failed at '${step}' for @${app}`, options);
+        this.name = 'AppSessionRefreshError';
+        this.step = step;
+    }
+}

package/dist/application/session/token.d.ts

@@ -0,0 +1,24 @@
+import type { UnresolvedIdentityExpr } from '@astrale-os/kernel-core';
+import type { KernelClient } from '../../kernel/client';
+/** The current token, plus the recipe that mints its successor. */
+export interface TokenSlot {
+    readonly token: string;
+    readonly expiresAt: number;
+    readonly recipe: UnresolvedIdentityExpr;
+}
+/** The app token's lifecycle: lazy first mint, single-flight refresh. */
+export interface TokenCycle {
+    current(): TokenSlot | null;
+    needsRefresh(): boolean;
+    /** Advance the slot via one delegate → getAccessToken exchange. Single-flight. */
+    refresh(): Promise<TokenSlot>;
+}
+export declare function createTokenCycle(opts: {
+    /** The shell kernel — dispatches AS THE USER, whose signature the delegate step needs. */
+    kernel: KernelClient;
+    appId: string;
+    /** `app::open`'s first ready-to-mint recipe. */
+    initialRecipe: UnresolvedIdentityExpr;
+    now: () => number;
+}): TokenCycle;
+//# sourceMappingURL=token.d.ts.map

package/dist/application/session/token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../../../src/application/session/token.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAA;AAErE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAcvD,mEAAmE;AACnE,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAA;CACxC;AAED,yEAAyE;AACzE,MAAM,WAAW,UAAU;IACzB,OAAO,IAAI,SAAS,GAAG,IAAI,CAAA;IAC3B,YAAY,IAAI,OAAO,CAAA;IACvB,kFAAkF;IAClF,OAAO,IAAI,OAAO,CAAC,SAAS,CAAC,CAAA;CAC9B;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,0FAA0F;IAC1F,MAAM,EAAE,YAAY,CAAA;IACpB,KAAK,EAAE,MAAM,CAAA;IACb,gDAAgD;IAChD,aAAa,EAAE,sBAAsB,CAAA;IACrC,GAAG,EAAE,MAAM,MAAM,CAAA;CAClB,GAAG,UAAU,CAgDb"}

package/dist/application/session/token.js

@@ -0,0 +1,51 @@
+import { REFRESH_WINDOW_MS } from '../../kernel/delegation/token';
+import { AppSessionRefreshError } from './session';
+export function createTokenCycle(opts) {
+    const { kernel, appId, now } = opts;
+    let slot = null;
+    let inFlight = null;
+    // One delegate → getAccessToken exchange, minting the NEXT token from the last
+    // recipe. On failure `slot` is untouched (the throw carries the failed step).
+    async function cycle() {
+        const recipe = slot?.recipe ?? opts.initialRecipe;
+        let envelope;
+        try {
+            envelope = await kernel.auth.delegate({ delegation: recipe });
+        }
+        catch (cause) {
+            throw new AppSessionRefreshError('delegate', appId, { cause });
+        }
+        let access;
+        try {
+            access = (await kernel.call(`@${appId}::getAccessToken`, {
+                delegation: envelope,
+            }));
+        }
+        catch (cause) {
+            throw new AppSessionRefreshError('getAccessToken', appId, { cause });
+        }
+        return { token: access.credential, expiresAt: access.expiresAt, recipe: access.delegation };
+    }
+    // Single-flight: concurrent callers share one in-flight cycle; the slot is
+    // only advanced on success.
+    function refresh() {
+        if (inFlight)
+            return inFlight;
+        const run = cycle()
+            .then((next) => {
+            slot = next;
+            return next;
+        })
+            .finally(() => {
+            if (inFlight === run)
+                inFlight = null;
+        });
+        inFlight = run;
+        return run;
+    }
+    return {
+        current: () => slot,
+        needsRefresh: () => slot === null || slot.expiresAt - now() - REFRESH_WINDOW_MS <= 0,
+        refresh,
+    };
+}

package/dist/application/spaces.d.ts

@@ -0,0 +1,17 @@
+import type { BoundNode, DefOf, NodeRefInput } from '@astrale-os/kernel-client';
+import type { KernelClient } from '../kernel/client';
+import type { ShellDomainView, ShellSchema } from './view';
+/** A workspace `Space` node. */
+export type SpaceNode = BoundNode<DefOf<ShellSchema, 'Space'>, ShellSchema>;
+export interface SpacesNamespace {
+    /** Children of the spaces directory — exactly the caller-readable spaces. */
+    list(): Promise<SpaceNode[]>;
+    /** One space by ref, or `null` when missing / masked / not a space. */
+    get(ref: NodeRefInput): Promise<SpaceNode | null>;
+    /** `Space.create` — creates the space (and selects it). */
+    create(opts?: {
+        name?: string;
+    }): Promise<SpaceNode>;
+}
+export declare function createSpacesNamespace(kernel: KernelClient, v: ShellDomainView): SpacesNamespace;
+//# sourceMappingURL=spaces.d.ts.map

package/dist/application/spaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spaces.d.ts","sourceRoot":"","sources":["../../src/application/spaces.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAI/E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAA;AAE1D,gCAAgC;AAChC,MAAM,MAAM,SAAS,GAAG,SAAS,CAAC,KAAK,CAAC,WAAW,EAAE,OAAO,CAAC,EAAE,WAAW,CAAC,CAAA;AAE3E,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,IAAI,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC,CAAA;IAC5B,uEAAuE;IACvE,GAAG,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAA;IACjD,2DAA2D;IAC3D,MAAM,CAAC,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,SAAS,CAAC,CAAA;CACrD;AAKD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,EAAE,eAAe,GAAG,eAAe,CA6B/F"}

package/dist/application/spaces.js

@@ -0,0 +1,30 @@
+import { normalizeRef } from '@astrale-os/kernel-client';
+/** The spaces directory (mirrors the workspace domain's `SPACES_DIR`). */
+const SPACES_DIR = '/spaces';
+export function createSpacesNamespace(kernel, v) {
+    return {
+        async list() {
+            const page = await kernel.children(SPACES_DIR);
+            const nodes = await page.all();
+            return nodes.flatMap((n) => {
+                const space = v.bindAs('Space', n);
+                return space ? [space] : [];
+            });
+        },
+        async get(ref) {
+            const node = await kernel.get(normalizeRef(ref));
+            return node ? v.bindAs('Space', node) : null;
+        },
+        async create(opts) {
+            // `Space.create`'s params are all-optional, so the typed dispatch collapses
+            // to `(opts?)`; the runtime still forwards a params object (resolveCallArgs),
+            // so pass `{ name }` through a create-shaped view of the same thunk.
+            const create = v.view()('Space').create;
+            const created = await create(opts?.name !== undefined ? { name: opts.name } : undefined);
+            const space = await v.view().node('Space', `@${created.id}`);
+            if (!space)
+                throw new Error(`Space.create: created space @${created.id} is not readable`);
+            return space;
+        },
+    };
+}

package/dist/application/user.d.ts

@@ -0,0 +1,20 @@
+import type { BoundNode, DefOf, NodeRefInput } from '@astrale-os/kernel-client';
+import type { KernelClient } from '../kernel/client';
+import type { SpaceNode } from './spaces';
+import type { ShellDomainView, ShellSchema } from './view';
+/** Self as the shell-domain `User` — typed `firstName`/`lastName`/`email`. */
+export type UserNode = BoundNode<DefOf<ShellSchema, 'User'>, ShellSchema>;
+/** A `Role` a user holds. */
+export type RoleNode = BoundNode<DefOf<ShellSchema, 'Role'>, ShellSchema>;
+export interface UserNamespace {
+    /** `whoami`, bound as the shell-domain `User`. */
+    me(): Promise<UserNode>;
+    /** The `selected_space` edge target, or `null` when none is selected. */
+    currentSpace(): Promise<SpaceNode | null>;
+    /** `user::switchSpace` — validate + repoint the `selected_space` edge. Idempotent. */
+    switchSpace(ref: NodeRefInput): Promise<void>;
+    /** The `has_role` out-edges of self. */
+    roles(): Promise<RoleNode[]>;
+}
+export declare function createUserNamespace(kernel: KernelClient, v: ShellDomainView): UserNamespace;
+//# sourceMappingURL=user.d.ts.map

package/dist/application/user.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user.d.ts","sourceRoot":"","sources":["../../src/application/user.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAI/E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AACzC,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAA;AAI1D,8EAA8E;AAC9E,MAAM,MAAM,QAAQ,GAAG,SAAS,CAAC,KAAK,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE,WAAW,CAAC,CAAA;AACzE,6BAA6B;AAC7B,MAAM,MAAM,QAAQ,GAAG,SAAS,CAAC,KAAK,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE,WAAW,CAAC,CAAA;AAEzE,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,EAAE,IAAI,OAAO,CAAC,QAAQ,CAAC,CAAA;IACvB,yEAAyE;IACzE,YAAY,IAAI,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAA;IACzC,sFAAsF;IACtF,WAAW,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7C,wCAAwC;IACxC,KAAK,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAA;CAC7B;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,EAAE,eAAe,GAAG,aAAa,CA2B3F"}

package/dist/application/user.js

@@ -0,0 +1,26 @@
+import { normalizeRef } from '@astrale-os/kernel-client';
+import { asArray } from './view';
+export function createUserNamespace(kernel, v) {
+    async function me() {
+        return v.view().bind('User', await kernel.auth.whoami());
+    }
+    return {
+        me,
+        async currentSpace() {
+            const self = await me();
+            const first = asArray(await self.out('selected_space'))[0];
+            return first ? v.bindAs('Space', first.raw) : null;
+        },
+        async switchSpace(ref) {
+            const self = await me();
+            await self.call.switchSpace({ space: normalizeRef(ref) });
+        },
+        async roles() {
+            const self = await me();
+            return asArray(await self.out('has_role')).flatMap((r) => {
+                const role = v.bindAs('Role', r.raw);
+                return role ? [role] : [];
+            });
+        },
+    };
+}

package/dist/application/view.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The typed plane the OS namespaces speak: `kernel.withSchema(schema)` over the
+ * workspace domain (`@astrale-domains/workspace-schema`). The bound view is built LAZILY
+ * (first call) so the sandboxed shell's "init() first" kernel guard applies
+ * uniformly — constructing namespaces touches no kernel.
+ */
+import type { BoundNode, DefOf, SchemaBoundView } from '@astrale-os/kernel-client';
+import type { Node } from '@astrale-os/kernel-core';
+import { schema } from '@astrale-domains/workspace-schema';
+import type { KernelClient } from '../kernel/client';
+export type ShellSchema = typeof schema;
+export interface ShellDomainView {
+    view(): SchemaBoundView<ShellSchema>;
+    /** Bind `node` as `type` when its concrete class satisfies it, else `null`. */
+    bindAs<T extends 'User' | 'Space' | 'Application' | 'Role'>(type: T, node: Node): BoundNode<DefOf<ShellSchema, T>, ShellSchema> | null;
+}
+export declare function createShellDomainView(kernel: KernelClient): ShellDomainView;
+/** Normalize a typed traversal result (single | array | null) to an array. */
+export declare function asArray<T>(result: T | readonly T[] | null): T[];
+//# sourceMappingURL=view.d.ts.map

package/dist/application/view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view.d.ts","sourceRoot":"","sources":["../../src/application/view.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAClF,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAA;AAEnD,OAAO,EAAE,MAAM,EAAE,MAAM,mCAAmC,CAAA;AAE1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAEpD,MAAM,MAAM,WAAW,GAAG,OAAO,MAAM,CAAA;AAEvC,MAAM,WAAW,eAAe;IAC9B,IAAI,IAAI,eAAe,CAAC,WAAW,CAAC,CAAA;IACpC,+EAA+E;IAC/E,MAAM,CAAC,CAAC,SAAS,MAAM,GAAG,OAAO,GAAG,aAAa,GAAG,MAAM,EACxD,IAAI,EAAE,CAAC,EACP,IAAI,EAAE,IAAI,GACT,SAAS,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE,WAAW,CAAC,GAAG,IAAI,CAAA;CACxD;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,YAAY,GAAG,eAAe,CAW3E;AAED,8EAA8E;AAC9E,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,SAAS,CAAC,EAAE,GAAG,IAAI,GAAG,CAAC,EAAE,CAG/D"}