init

lib/types/index.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Public surface of the `dsh-facet` host row.
+ *
+ * The augmentation below is the point of this file: `ctx.facetPolicy` is a
+ * service published by `provide`, so without it a TypeScript consumer sees the
+ * property as missing. The preset half (`dsh-facet/guard`) is typed in
+ * `./guard.d.ts`.
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type z from '@deepseek-ai/schemastery'
+
+/** One session's resolved scope. */
+export interface FacetScope {
+  /** The session working directory, absolute — also the boundary. */
+  readonly cwd: string
+  /** The facet root; the session's own folder. */
+  readonly root: string
+  /** Absolute granted paths outside the root: standing grants, then this session's. */
+  readonly extras: string[]
+}
+
+/** How an out-of-scope call is handled. */
+export type FacetMode = 'ask' | 'deny' | 'off'
+
+/** The deployment's facet policy, published by the host row. */
+export interface FacetPolicy {
+  readonly mode: FacetMode
+  /** System-prompt placement of the invariant rule. */
+  readonly sectionOrder: number
+  /** Runtime-context placement of the per-session binding. */
+  readonly contextOrder: number
+  /** Every path always in scope, as configured. */
+  readonly standing: string[]
+  /** Session ids currently holding a grant. */
+  readonly sessions: string[]
+  /** The scope of one agent, or `undefined` when it has no working directory. */
+  scopeFor(agent: { session?: { id?: unknown; header?: { cwd?: unknown } } } | undefined): FacetScope | undefined
+  /** Add paths to one session's grants. */
+  grant(sessionId: string, paths: readonly string[], cwd: string): string[]
+  /** Drop paths from one session's grants. */
+  revoke(sessionId: string, paths: readonly string[], cwd: string): string[]
+  /** Clear one session's grants. */
+  reset(sessionId: string): string[]
+  /** One session's own grants, without the standing ones. */
+  grantsFor(sessionId: string): string[]
+  /** Drop a finished session's grants. */
+  forget(sessionId: string): void
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    /** Published by `dsh-facet`; consumed by `dsh-facet/guard`. */
+    facetPolicy: FacetPolicy
+  }
+}
+
+/** Plugin name. */
+export declare const name = 'dsh-facet'
+
+/** Configuration: the deployment's facet policy. */
+export interface Config {
+  /** How an out-of-scope call is handled. Defaults to `ask`. */
+  mode?: FacetMode
+  /** Paths always in scope; relative paths resolve against each session's directory. */
+  extraRoots?: string[]
+  /** Placement of the invariant rule in the system prompt. Defaults to `100`. */
+  sectionOrder?: number
+  /** Placement of the per-session binding in the runtime-context snapshot. Defaults to `105`. */
+  contextOrder?: number
+}
+
+export declare const Config: z<Config>
+
+export declare function apply(ctx: Context, config: Config): void