feat: add core value, planner and error types to match the Python SDK

core/src/main/java/com/google/adk/agents/TranscriptionEntry.java

@@ -0,0 +1,87 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * 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 com.google.adk.agents;
+
+import com.google.auto.value.AutoValue;
+import com.google.common.base.Preconditions;
+import com.google.genai.types.Blob;
+import com.google.genai.types.Content;
+import java.util.Optional;
+import org.jspecify.annotations.Nullable;
+
+/**
+ * Stores the data that can be used for transcription.
+ *
+ * <p>A live audio invocation caches one of these per thing that was said, so that the audio can be
+ * bundled by speaker and transcribed later.
+ *
+ * <p>An entry carries either a {@link Blob} of audio that still needs recognising or a {@link
+ * Content} of text the model already produced, never both and never neither. The two are separate
+ * fields rather than one field of an open type, the same way {@link LiveRequest} carries the same
+ * pair.
+ */
+@AutoValue
+public abstract class TranscriptionEntry {
+
+  TranscriptionEntry() {}
+
+  /**
+   * Returns the role that created this data, typically {@code "user"} or {@code "model"}.
+   *
+   * <p>Empty for a function call, which nobody spoke.
+   */
+  public abstract Optional<String> role();
+
+  /** Returns audio that still needs recognising, empty when the entry carries text instead. */
+  public abstract Optional<Blob> blob();
+
+  /** Returns text the model already produced, empty when the entry carries audio instead. */
+  public abstract Optional<Content> content();
+
+  /** Returns a new builder for creating a {@link TranscriptionEntry}. */
+  public static Builder builder() {
+    return new AutoValue_TranscriptionEntry.Builder();
+  }
+
+  /** Returns a new builder with a copy of this entry's values. */
+  public abstract Builder toBuilder();
+
+  /** Builder for {@link TranscriptionEntry}. */
+  @AutoValue.Builder
+  public abstract static class Builder {
+
+    /** Sets the role that created this data. */
+    public abstract Builder role(@Nullable String role);
+
+    /** Sets audio that still needs recognising as the data of this entry. */
+    public abstract Builder blob(@Nullable Blob blob);
+
+    /** Sets text the model already produced as the data of this entry. */
+    public abstract Builder content(@Nullable Content content);
+
+    abstract TranscriptionEntry autoBuild();
+
+    /** Builds the entry, refusing one that carries neither kind of data or both. */
+    public final TranscriptionEntry build() {
+      TranscriptionEntry entry = autoBuild();
+      Preconditions.checkState(
+          entry.blob().isPresent() != entry.content().isPresent(),
+          "Exactly one of blob or content must be set");
+      return entry;
+    }
+  }
+}

core/src/main/java/com/google/adk/artifacts/ArtifactVersion.java

@@ -0,0 +1,71 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * 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 com.google.adk.artifacts;
+
+import com.google.auto.value.AutoValue;
+import com.google.common.collect.ImmutableMap;
+import java.time.Instant;
+import java.util.Map;
+import java.util.Optional;
+import org.jspecify.annotations.Nullable;
+
+/**
+ * Metadata describing a specific version of an artifact.
+ *
+ * <p>This describes a stored payload without being one, so a caller can learn where a version
+ * lives, what type it is and what was attached to it without downloading it.
+ */
+@AutoValue
+public abstract class ArtifactVersion {
+
+  ArtifactVersion() {}
+
+  /** Monotonically increasing identifier for the artifact version. */
+  public abstract int version();
+
+  /** Canonical URI referencing the persisted artifact payload. */
+  public abstract String canonicalUri();
+
+  /** Metadata the caller attached to the artifact, empty when none was attached. */
+  public abstract ImmutableMap<String, Object> customMetadata();
+
+  /** When the version record was created. */
+  public abstract Instant createTime();
+
+  /** MIME type of the payload, empty when the store does not know it. */
+  public abstract Optional<String> mimeType();
+
+  public static Builder builder() {
+    return new AutoValue_ArtifactVersion.Builder().customMetadata(ImmutableMap.of());
+  }
+
+  /** Builder for {@link ArtifactVersion}. */
+  @AutoValue.Builder
+  public abstract static class Builder {
+    public abstract Builder version(int version);
+
+    public abstract Builder canonicalUri(String canonicalUri);
+
+    public abstract Builder customMetadata(Map<String, Object> customMetadata);
+
+    public abstract Builder createTime(Instant createTime);
+
+    public abstract Builder mimeType(@Nullable String mimeType);
+
+    public abstract ArtifactVersion build();
+  }
+}

core/src/main/java/com/google/adk/events/UiWidget.java

@@ -0,0 +1,105 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * 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 com.google.adk.events;
+
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
+import com.google.adk.JsonBaseModel;
+import com.google.auto.value.AutoValue;
+import com.google.common.collect.ImmutableMap;
+import java.util.Map;
+
+/**
+ * Rendering metadata for a UI widget associated with an event.
+ *
+ * <p>An agent emits one of these to ask the UI to draw something richer than text. The UI picks a
+ * renderer from the named provider and hands it the payload.
+ */
+@AutoValue
+@JsonDeserialize(builder = UiWidget.Builder.class)
+public abstract class UiWidget extends JsonBaseModel {
+
+  UiWidget() {}
+
+  /** Returns the unique identifier of the UI widget. */
+  @JsonProperty("id")
+  public abstract String id();
+
+  /**
+   * Returns the widget provider identifier, which determines the rendering strategy the UI uses.
+   *
+   * <p>Known values:
+   *
+   * <ul>
+   *   <li>{@code mcp}: MCP App iframe, rendered with the MCP Apps AppBridge.
+   * </ul>
+   */
+  @JsonProperty("provider")
+  public abstract String provider();
+
+  /**
+   * Returns the provider-specific data required for rendering, empty when the provider needs none.
+   *
+   * <p>If the provider is {@code mcp}, the payload holds {@code resource_uri}, {@code tool} and
+   * {@code tool_args}. Future providers bring their own fields, so the keys are the provider's
+   * rather than this SDK's.
+   */
+  @JsonProperty("payload")
+  public abstract ImmutableMap<String, Object> payload();
+
+  /** Returns a new builder for creating a {@link UiWidget}. */
+  public static Builder builder() {
+    return new AutoValue_UiWidget.Builder().payload(ImmutableMap.of());
+  }
+
+  /** Returns a new builder with a copy of this widget's values. */
+  public abstract Builder toBuilder();
+
+  /** Builder for {@link UiWidget}. */
+  @AutoValue.Builder
+  public abstract static class Builder {
+
+    @JsonCreator
+    static Builder create() {
+      return UiWidget.builder();
+    }
+
+    /**
+     * Sets the unique identifier of the UI widget.
+     *
+     * <p>This is a required field.
+     */
+    @JsonProperty("id")
+    public abstract Builder id(String id);
+
+    /**
+     * Sets the widget provider identifier.
+     *
+     * <p>This is a required field.
+     */
+    @JsonProperty("provider")
+    public abstract Builder provider(String provider);
+
+    /** Sets the provider-specific data required for rendering, copying the given map. */
+    @JsonProperty("payload")
+    public abstract Builder payload(Map<String, Object> payload);
+
+    /** Builds the immutable {@link UiWidget} object. */
+    public abstract UiWidget build();
+  }
+}