@saguiitay/eventhouse-ai-observability 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 0.1.1 - 2026-11-12
+
+- Fix the reported development-dependency advisories by upgrading AJV to 8.18.0
+  and fast-uri to 3.1.9.
+- Publish with public access and require verified public GitHub package visibility
+  before publication. GitHub's one-time package visibility setting is separate
+  from npm's access flag.
+- Derive the package-smoke tarball name from release metadata, and verify packed
+  metadata, instrumentation scope version, and the basic example's dependency pin.
+- Update the basic example to consume published 0.1.1 once that version is released.
+- Document successful operator-reported live validation of 0.1.0: installed
+  package, Copilot execution, Eventstream acknowledgement, Eventhouse ingestion,
+  and dashboard visibility. This does not claim automated live validation of 0.1.1.
+
+## 0.1.0 - 2026-11-12
+
+- Initial GitHub Packages release with Fabric Eventstream and OTLP export,
+  GitHub Copilot SDK instrumentation, privacy filtering, and export diagnostics.
+- Include Fabric schemas, analytics, dashboard assets, provisioning tools,
+  three Copilot examples, offline tests, and an opt-in live validation script.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eventhouse AI Observability contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,183 @@
-# Temporary Holding Version
+# Five-minute quick start
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Instrument an **existing GitHub Copilot SDK session** and send OpenTelemetry spans directly to Microsoft Fabric Eventstream. No Collector, gateway, or custom frontend.
+
+1. In Fabric, add an Eventstream **Custom endpoint source**, then connect its output to an Eventhouse KQL database. Use the source's **Event Hub** producer credentials, not an outward destination. Apply the [schema and setup](docs/fabric-setup.md).
+2. Set `FABRIC_EVENTSTREAM_CONNECTION_STRING` to the Fabric-provided connection string. If it omits `EntityPath`, also set `FABRIC_EVENTSTREAM_ENTITY_NAME` to the provided event hub name.
+3. Configure [GitHub Packages authentication](#installation-from-github-packages), then install and instrument:
+
+```sh
+npm install @saguiitay/eventhouse-ai-observability
+```
+
+```typescript
+import { observeCopilot } from "@saguiitay/eventhouse-ai-observability/copilot";
+
+const session = await copilot.createSession(/* your existing configuration */);
+const observer = observeCopilot(session, {
+  connectionString: process.env.FABRIC_EVENTSTREAM_CONNECTION_STRING!,
+  serviceName: "my-agent",
+});
+
+try {
+  await session.sendAndWait({ prompt: "Explain distributed tracing." });
+} finally {
+  await observer.shutdown();
+}
+```
+
+Version 0.1.1 is published to **GitHub Packages**. A separate npmjs workflow
+stages the same version for human approval; it does not publish directly.
+Until the first npmjs approval, use the GitHub Packages installation below.
+To test an unpublished release,
+run `pnpm install` and `pnpm pack`; install the root tarball with npm.
+Node.js **22.15+** (including Node 24 LTS), ESM, Copilot SDK **1.0.31** / compatible
+1.x, and a Fabric capacity/workspace with Eventstream and Eventhouse are required.
+The repository's `.npmrc` routes only `@saguiitay` packages to GitHub Packages;
+other dependencies continue to use your configured, organization-approved registry.
+
+Packing with `pnpm pack` or `npm pack` automatically rebuilds the ESM runtime and
+TypeScript declarations through `prepack`; a failed build stops packaging. Do not
+disable lifecycle scripts when preparing a release.
+
+The tarball includes these documentation pages and example sources/templates, so
+relative links work from the installed package. Run example/provisioning commands
+from the source checkout; Fabric assets remain there and are not shipped with
+tenant-specific bindings.
+
+Metadata only is captured by default. Prompts, responses, tool arguments, tool results, and error messages are not collected unless explicitly enabled. Credentials are redacted; review [security](docs/security.md) before enabling content.
+
+## What is included
+
+One npm package with root and `/copilot` exports and ordinary internal modules under `src`. OpenTelemetry supplies batching, sampling, and OTLP export; our code supplies the Fabric exporter, privacy filtering, and Copilot event adapter. Includes versioned JSON, Eventhouse schema and twenty analytics queries, native dashboard assets, provisioning, three [examples](examples), local integration tests, and an opt-in live check.
+
+```typescript
+import { createObservability } from "@saguiitay/eventhouse-ai-observability";
+
+const observer = createObservability({
+  transport: "otlp",
+  endpoint: "https://your-existing-otlp-service.example/v1/traces",
+});
+const span = observer.startSpan("invoke_agent my-framework", {
+  attributes: { "gen_ai.operation.name": "invoke_agent" },
+});
+span.end();
+await observer.flush();
+await observer.shutdown();
+```
+
+An OTLP endpoint is optional and **not required for Fabric**. Eventstream receives JSON events over the official Event Hubs AMQP producer protocol, not OTLP.
+
+Examples print their selected transport and final export counters, and fail after
+cleanup if telemetry failed or was dropped. In applications, use
+`observer.getDiagnostics().lastError`, `onDiagnostic`, or `debug: true` for safe
+failure categories without exposing credentials. Producer acknowledgements do
+not prove Eventhouse ingestion. Existing Fabric deployments can use the
+[previewable update command](docs/fabric-setup.md#updating-an-existing-deployment)
+to update the helper and dashboard queries without replacing bindings.
+
+## Development and verification
+
+```sh
+pnpm install
+pnpm typecheck
+pnpm test
+pnpm build
+pnpm lint
+pnpm validate:fabric
+pnpm bench
+```
+
+All SDK and asset/schema tests run in Node/TypeScript with Vitest and Ajv. Fabric provisioning and its mocked REST tests require PowerShell 7.2+; Python is not required.
+
+`pnpm test` uses SDK mocks and a real localhost OTLP HTTP receiver. It does **not**
+establish Fabric compatibility. **Live Fabric compatibility: verified for the
+operator's 0.1.0 deployment on 2026-11-12**, based on the operator's reported
+published-package installation, successful Copilot execution, three acknowledged
+spans with no drops/failures, rows in `AIObservabilityTraces`, and dashboard
+visibility. This does not establish support for all tenants, automated
+provisioning, or a live run of 0.1.1. The separate [live validation
+script](docs/quickstart.md#live-fabric-validation) checks producer acceptance,
+Eventhouse ingestion, KQL lookup, and parent-child relationships; its execution
+has not been reported.
+
+## Installation from GitHub Packages
+
+GitHub's npm registry requires authentication even for public packages. Your
+organization must permit access to `https://npm.pkg.github.com`.
+Add this scope mapping to the consuming project's `.npmrc`:
+
+```ini
+@saguiitay:registry=https://npm.pkg.github.com
+```
+
+Create a personal access token **(classic)** with `read:packages`. In PowerShell 7,
+configure a user-level environment-variable reference instead of using the
+`npm login` endpoint, which may return HTTP 403:
+
+```powershell
+$env:GITHUB_PACKAGES_TOKEN = Read-Host "GitHub classic PAT" -MaskInput
+npm config set '//npm.pkg.github.com/:_authToken' '${GITHUB_PACKAGES_TOKEN}' --location=user
+npm install @saguiitay/eventhouse-ai-observability
+```
+
+Keep credentials in user-level configuration or your CI secret store, never in
+the repository. Set the environment variable again in each new terminal session.
+This scope mapping does not change the registry for dependencies outside `@saguiitay`.
+
+## Publishing
+
+Run **Publish to GitHub Packages** from the repository's Actions tab on `main`,
+or publish a GitHub Release whose tag matches the package version, such as
+`v0.1.1`. Update `package.json`, the instrumentation scope version in `src/engine.ts`,
+and the basic example's dependency pin before releasing another version; published versions
+cannot be overwritten. Prerelease versions use the `next` dist-tag instead of `latest`.
+
+The workflow first verifies that the existing GitHub package is public, then
+validates, builds via `prepack`, smoke-tests the tarball, publishes that exact
+artifact with `--access public`, and checks its registry version. It uses the repository's
+`GITHUB_TOKEN` with `packages: write`; no npm token or personal access token secret
+is needed for publishing. Repository/organization Actions policy must allow this
+permission.
+
+GitHub controls visibility separately from npm's access flag. Before the next
+publication, open the existing package's **Package settings → Change visibility**
+and select **Public**. This is a one-time, irreversible setting; all subsequent
+versions of this package remain public. The workflow fails before publishing if
+the package is private or its visibility cannot be verified. New package names
+must be bootstrapped and made public before using this workflow.
+Public visibility still requires consumer authentication. See the [release notes](CHANGELOG.md).
+
+## Staging on npmjs
+
+The separate **Stage package on npmjs** workflow runs manually on `main`. It uses
+Node 24 and npm 12, validates the project, changes the registry only in its runner
+checkout, packs, smoke-tests, and stages the exact tested tarball. The committed
+GitHub Packages registry configuration and its publishing workflow are unchanged.
+Packed metadata is checked against the selected publication settings.
+
+For the first npmjs publication:
+
+1. Own the `@saguiitay` npm scope and enable npm account 2FA.
+2. Create a short-lived granular token with **Read and write (stage only)**
+   permission for that scope. Leave **Bypass two-factor authentication** unchecked.
+3. Store the token as the repository Actions secret **`NPM_STAGING_TOKEN`**.
+   The workflow exposes it only to the staging step, never to dependency installation
+   or package lifecycle scripts.
+4. Run **Stage package on npmjs** from Actions. On npmjs.com, open **Account >
+   Staged Packages**, review the package/version, and **Approve** with 2FA.
+
+For a new package, npm creates a publicly visible `0.0.0-stage` placeholder.
+The actual staged version's contents remain unavailable until approval. A staged
+version reserves that version number; do not rerun staging for an already staged
+or published version. `0.1.1` on GitHub Packages does not reserve `0.1.1` on npmjs.
+
+After bootstrap, configure npm's GitHub Actions trusted publisher for
+`saguiitay/ai-observability` and workflow filename `publish-npmjs.yml`, update the
+workflow to use OIDC, and revoke the bootstrap token. Approval still requires
+interactive 2FA if using staged publishing. See [npm staged publishing](https://docs.npmjs.com/staged-publishing/)
+and [trusted publishing](https://docs.npmjs.com/trusted-publishers/).
+
+## Documentation
+
+[Quickstart](docs/quickstart.md) · [Architecture](docs/architecture.md) · [Research](docs/research.md) · [Fabric setup](docs/fabric-setup.md) · [Transport](docs/eventstream-transport.md) · [Schema](docs/telemetry-schema.md) · [Copilot adapter](docs/copilot-adapter.md) · [Dashboards](docs/dashboards.md) · [Security](docs/security.md) · [Extending](docs/extending.md) · [Troubleshooting](docs/troubleshooting.md) · [Performance](docs/performance.md) · [Implementation report](docs/implementation-report.md).

package/dist/adapters/copilot.d.ts

@@ -0,0 +1,18 @@
+import type { SessionEventHandler } from "@github/copilot-sdk";
+import type { Diagnostics, Observability } from "../engine.js";
+/** Compatible with CopilotSession without requiring its private implementation. */
+export interface CopilotEventSource {
+    readonly sessionId: string;
+    on(handler: SessionEventHandler): () => void;
+}
+export interface CopilotObserver {
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+    getDiagnostics(): Readonly<Diagnostics>;
+}
+export interface AttachCopilotOptions {
+    /** Defaults to true. Use false when several adapters share an externally owned engine. */
+    shutdownEngine?: boolean;
+}
+/** Attaches synchronously; event callbacks never perform or await network I/O. */
+export declare function attachCopilot(session: CopilotEventSource, engine: Observability, options?: AttachCopilotOptions): CopilotObserver;